Webhook events and delivery

Register HTTPS endpoints to receive signed events as connections progress, as monitored domains drift, as nameserver moves go through and as the API keys a secure sign-in made near their end.

Register an endpoint

curl -X POST https://api.customdomain.ai/v1/webhooks \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://api.acme.example/webhooks/cd","events":["connection.live","domain.record_missing"]}'
# → { "id": "whk_…", "url": "...", "events": [...], "secret": "whsec_…", "created_at": "..." }

Register from your server with an API key (or an app-scoped widget token). A widget token minted by POST /v1/tokens has connect scope and is rejected with 403. The url must be a public https URL; localhost and private or link-local addresses are refused.

An empty events array subscribes to all events; "*" also matches all.

Manage endpoints: GET /v1/webhooks lists them (secrets omitted; tenant-wide with an API key, app-scoped with a widget JWT; ?app_id= narrows to one application) and DELETE /v1/webhooks/{id} removes one (204). The tenant-wide list leaves out a test mode application's endpoints unless ?app_id= names it, so a test endpoint is never mistaken for a live one.

Event catalog

When the connection carries a recorded diagnosis at emit time, the envelope also includes error_code and error_message (for example propagation_timeout, access_denied, ProviderAuthenticationError, or setup_incomplete on a stalled pending connection), so a receiver need not fetch the connection to learn why.

That table is the complete vocabulary: it is exactly the set the platform can emit, and the events enum in the OpenAPI spec matches it. An unknown event string is still accepted at registration, but it can never be delivered, so subscribe only to the events above.

Payload envelope

Deliveries are a flat JSON object:

{
  "id": "evt_…",
  "type": "connection.live",
  "user_id": "tenant-or-end-user-ref",
  "domain": "app.customer.com",
  "subdomain": "app",
  "provider": "cloudflare",
  "setup_type": "automatic",
  "propagation_status": "success",
  "data": {
    "records_propagated": [ { "type": "CNAME", "host": "app.customer.com", "value": "edge.customdomain.ai" } ],
    "records_non_propagated": []
  },
  "created_at": "2026-07-07T12:00:00Z"
}

propagation_status is pending, success, or timeout. On propagation events, data carries the per-record propagated / non-propagated arrays. Fields that don't apply to an event are omitted.

Additional conditional fields ride connection events:

• user_id: the connection's end_user_ref, echoed so integrators can associate lifecycle events with the originating tenant or end user. Omitted when the connection was created without an end_user_ref. A connection made from the console's Try it live carries console:<member id> here, a prefix the console reserves for its own tests and never one of your customers, so a receiver can skip it.

• updated_objects: the records a write actually created or changed. Present on connection.applied and connection.records.updated only; the events that just observe a connection never claim to have written anything.

• redirection_status: pending, success or failed for the apex↔www redirect, and present only on connections created with www_redirect: true whose domain is on the CustomDomain™ edge. A domain on your own infrastructure omits it: the edge serves no redirect there, so the redirect is yours to serve.

• connection_id: the connection the event is about, on connection, certificate and drift events.

• nameservers: on every nameservers.* event, the move it is about: migration_id, zone (the registrable domain), state, path (api, agent or manual), target (managed, dns_host or custom), old_nameservers and new_nameservers, and where they apply observed_nameservers (what the registry lists, on nameservers.active and nameservers.drifted), failure_code (on nameservers.failed, and delegation_drift on nameservers.drifted), records_copied and email_records (how many of the copied records carry mail). When they are known it also carries registrar, the company the domain is registered with, where the nameservers are changed (name, our provider id when we connect to it, and iana_id, its IANA Registrar ID), and old_dns_host, the DNS host the domain left (a provider id such as cloudflare). On nameservers.rolled_back, rollback_target says where the move back went: previous (the nameservers the domain had) or registrar_default (the registrar's own DNS). Each event is also written to the domain's timeline as a row of the same kind.

  "nameservers": {
    "migration_id": "nsm_…",
    "zone": "acme.com",
    "state": "active",
    "path": "api",
    "target": "managed",
    "registrar": { "name": "GoDaddy", "provider": "godaddy", "iana_id": 146 },
    "old_dns_host": "cloudflare",
    "old_nameservers": ["ada.ns.cloudflare.com", "bob.ns.cloudflare.com"],
    "new_nameservers": ["ns-1402.awsdns-47.org", "ns-905.awsdns-49.net"],
    "observed_nameservers": ["ns-1402.awsdns-47.org", "ns-905.awsdns-49.net"],
    "records_copied": 14,
    "email_records": 5
  }

  The shape is illustrative: the values are made up.

• credential: on every credential.* event, the lasting API key it is about, never the key itself: account_id (the provider account that holds it), provider, status (active, renewed, expiring, needs_reconnect, expired or removed), key_name, scopes, expires_at (absent for a key with no end date), days_left (on credential.expiring), reason (refused, expired, expiring, not_kept or reconnect_failed), revoke_url (the provider's page where the key is revoked), rights (what it can do beyond the domain's DNS: transfer, billing or account; see rights) and reconnect: true when your customer should sign in again, with POST /v1/connections/{id}:reconnect-link or the widget's mode: "reconnect". connection_id names the domain's connection.

  "credential": {
    "account_id": "pacct_…",
    "provider": "hostinger",
    "status": "expiring",
    "key_name": "CustomDomain Acme Sites",
    "expires_at": "2026-11-19T12:00:00Z",
    "days_left": 30,
    "reason": "expiring",
    "revoke_url": "https://hpanel.hostinger.com/api",
    "rights": ["account"],
    "reconnect": true
  }

  The shape is illustrative: the values are made up. scopes is left out for a provider whose keys have none, as here.

• sandbox: true on an event from a test mode application, whose domain is a simulated .test name. Real events carry no sandbox field. Test mode events are signed and delivered like any other, so you can test your receiver end to end, and a receiver that writes to a real customer's account should check the field and skip them.

Delivery & retries

• A delivery succeeds on any 2xx. Respond within 15 seconds.
• Network errors, 5xx and 429 are retried with exponential backoff (about 30 seconds, then doubling, capped at 6 hours between tries), up to 12 attempts in total. Any other 4xx is treated as a permanent failure and is not retried.
• Inspect outcomes: GET /v1/webhook-deliveries returns the 100 most recent settled deliveries (attempts, status_code, delivered, error; filter with ?app_id= and ?type=). The log keeps the last 50 per application. A delivery that is still being retried appears once it succeeds or is given up on.

Endpoints should be idempotent: the same event can arrive more than once on retry. Deduplicate on the envelope id, or on domain + type.

Next: verify signatures.