Webhooks
Register endpoints, verify deliveries, rotate secrets, and replay safely.
Register a destination with POST /v1/webhook_endpoints.
The created response returns signing-secret material once; store it immediately
in a secret manager. Endpoint reads expose configuration and health, never the
secret value.
Verify every request against the exact raw body before parsing JSON. Respond quickly after durable acceptance in your system, and process asynchronously. Use the event ID as the deduplication key.
GET /v1/webhook_deliveries exposes delivery attempts
and outcomes. If a bounded historical range needs redelivery, create a replay
under the endpoint and poll that replay’s status. Replay creation has its own
idempotency key; use a stable key when retrying the same replay request.
Adding a signing secret starts a rotation window. Deploy verification for both active secrets before retiring the old one. Disabling an endpoint is a cutoff, not a pause: events produced while disabled are not silently queued for later.