Overview

Register HTTPS endpoints to receive signed events as connections progress and as monitored domains drift.

Register an endpoint

curl -X POST http://localhost:8080/v1/webhooks \
  -H "Authorization: Bearer <WIDGET_JWT>" \
  -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": "..." }

The secret (whsec_…) is returned once — store it to verify signatures. An empty events array subscribes to all events; "*" also matches all.

Manage endpoints: GET /v1/webhooks lists them (secrets omitted; tenant-wide with an sk_ key, app-scoped with a widget JWT) and DELETE /v1/webhooks/{id} removes 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 — subscribe only to the events above.

Status: the drift events (domain.record_missing / domain.record_restored) are produced by the hourly Monitor sweep, which delivers them only where MONITOR_ALERTS_ENABLED=1. With the flag off (the hosted default) the sweep still runs in shadow mode but no drift webhooks are sent. domain.purchased (and purchase.error) require the Sell purchase path, which is live on the hosted service (gated by SELL_PURCHASE_ENABLED).

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.
• 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.

Delivery & retries

• A delivery succeeds on any 2xx. Each attempt is persisted.
• Failures retry with exponential backoff, up to 3 attempts total.
• Inspect attempts: GET /v1/webhook-deliveries (attempts, status_code, delivered, error; filter with ?app_id= and ?type=).

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.