Webhooks

Registering an endpoint

Add a webhook endpoint from Dashboard → Settings → Developer → Webhooks with a name, a public HTTPS URL on port 443, and the event types to receive.

New endpoints start in pending_verification and receive no real events until they pass a verification challenge.

URLs are validated against SSRF: only public HTTPS hostnames are allowed — no localhost, private/link-local ranges, or cloud metadata addresses — and this check is repeated immediately before every delivery (DNS rebinding protection).

Verification and testing

Verifying sends a signed POST with a random challenge token; your endpoint must respond 2xx and echo `{ "challenge": "<token>" }` in its JSON body.

Once active, use "Send test event" to confirm your receiver is reachable and correctly validates signatures before relying on real traffic.

Signature verification

Every delivery includes `x-webhook-signature: v1=<hex hmac>` and `x-webhook-timestamp: <unix seconds>` headers.

Recompute HMAC-SHA256 over `${timestamp}.${rawBody}` using your endpoint's signing secret, compare it to the provided signature using a constant-time comparison, and reject requests with a stale timestamp.

The signing secret is shown once at creation or rotation time and is never retrievable afterward — rotate it immediately if it may have leaked.

Retries and limits

Failed deliveries (5xx or a timeout) retry on an exponential backoff schedule up to 7 attempts before being marked exhausted.

An endpoint that accumulates too many consecutive failures is automatically disabled and must be re-enabled after the underlying issue is fixed.

Endpoint counts per workspace are limited by plan; see the API documentation for authentication and idempotency shared with the REST API.