Webhooks
Overview
Register HTTPS endpoints to receive signed events as connections progress.
Register HTTPS endpoints to receive signed events as connections progress.
Register an endpoint
curl -X POST http://localhost:8080/v1/webhook-endpoints \
-H "Authorization: Bearer <YOUR_KEY>" \
-H "Content-Type: application/json" \
-d '{"url":"https://api.acme.example/webhooks/cd","events":["ssl.issued","domain.drift"]}'
# → { "id": "...", "url": "...", "events": [...], "signing_secret": "..." }The signing_secret is returned once — store it to verify signatures. An
empty events array subscribes to all events.
Event catalog
| Event | Fires when | data |
|---|---|---|
domain.added | A delegated auto-write succeeded at create; connection → propagating. | {hostname, setup_type:"automatic"} |
domain.verified | Ownership TXT confirmed; connection → verified. | {hostname} |
ssl.issued | All records propagated, cert mirror written; connection → live. | {hostname} |
domain.flow.completed | Fired together with ssl.issued on go-live. | {hostname} |
domain.drift | A live domain's records stopped resolving correctly; → drifted. | {hostname} |
ssl.issued and domain.flow.completed always fire as a pair on the live
transition, exactly once (a compare-and-swap guarantees a single actor — the API
records:check or the background worker — fires them and meters usage).
Payload envelope
{
"type": "ssl.issued",
"jobId": "<connection id>",
"data": { "hostname": "app.customer.com" },
"sent_at": "2026-07-02T12:00:00Z"
}jobId is the connection UUID.
Delivery, retries, and replay
- A delivery is a success on any
2xx; the HTTP client times out at 5s. - Every attempt is persisted. Failures retry with exponential backoff (1, 2, 4, 8, 16, 32 minutes, capped at 60) up to 6 attempts.
- Inspect deliveries:
GET /v1/webhook-deliveries(status, attempts,next_retry_at). - Re-send manually:
POST /v1/webhook-deliveries/{id}/replay— also available as a button in the console's Webhooks view.
Endpoints should be idempotent: the same event may be delivered more than
once (retries, replays). Deduplicate on jobId + type.
See Verifying signatures next.