Webhooks

Register a webhook endpoint (secret returned once)

Registers an HTTPS receiver under the calling application. The secret (whsec_…) is returned ONCE. Store it to verify signatures. An empty events array subscribes to all events; "*" also matches all.

post/webhooks

Request

  • Base URL: https://api.customdomain.ai/v1
  • URL: https://api.customdomain.ai/v1/webhooks
  • Auth: HTTP bearer

Request body

urlstring uri required
eventsstring[]

Event types to subscribe to; empty subscribes to all events, and "*" also matches all. Every value listed here has a producer: the enum is asserted against the emit sites in CI, so you can never subscribe to an event that cannot arrive. connection.records.updated / connection.reapply.failed / connection.disconnected cover the managed (async one-click) re-apply and disconnect lifecycle; connection.disconnected carries a removal object saying what happened to the DNS records. certificate.issued / certificate.renewed / certificate.failed follow the edge's certificate reports, and certificate.expiring fires 14, 7 and 3 days before an unrenewed certificate expires and when it expired; each carries a certificate object. domain.record_missing / domain.record_restored carry a drift object with the record, what public DNS shows and what was done about it. connection.records_outdated fires once per domain a routing change moves (saving a connect target, or POST /v1/connections/{id}:retarget), carrying records.previous and records.current; the domain needs the new records. certificate.failed fires once per failure episode, when the edge first reports that issuing or renewing the certificate failed. secure_status is sent only where the deployment has Secure on (SECURE_ENABLED), once each time a certificate's status changes. Every connection, certificate and routing event also appears on the domain's timeline (GET /v1/connections/{id}/events) as a row of the same kind.

Response

Created (secret returned once)

idstring required
application_idstring
urlstring uri required
eventsstring[]
secretstring nullable

Present ONLY in the creation response (whsec_…). Deliveries are signed with it: each POST carries X-JE-Timestamp (unix seconds) and X-JE-Signature (sha256=hex of HMAC-SHA256 over "<timestamp>.<rawBody>"). Reject deliveries whose timestamp is outside a ~5-minute window.

created_atstring date-time

Changes

No recorded changes to this operation across all 1 revision of this API.