Webhooks

Delivery guarantees: read before you build a receiver

At-least-once delivery

A delivery is retried on a transient failure (5xx, timeout, network error) on a schedule spanning roughly 5 seconds to 6 hours between attempts, for up to ~10 hours total, before it is abandoned. Your receiver must be idempotent: dedupe on the stable webhook-id header, which stays IDENTICAL across every retry of one delivery. A genuine re-send via POST /webhooks/deliveries/{deliveryId}/replay gets a fresh webhook-id, since it's a deliberate new delivery, not a retry.

NOT ordered

Two deliveries for the same account can arrive out of order (different endpoints, different retry timing, network jitter). Use the envelope's sequence field (monotonically increasing PER ACCOUNT, never per endpoint) as a last-writer-wins guard: discard an envelope whose sequence for a given resource is lower than one you've already processed.

At-most-once emission

The underlying OCCURRENCE (not delivery) is recorded once; a retried producer can never cause the same occurrence to be recorded twice. This is orthogonal to delivery being at-least-once: ONE occurrence can still be DELIVERED more than once to the same endpoint (a retry after a timeout whose response you never saw, for instance), and that's exactly what webhook-id-based dedupe on your end is for.

3xx and 4xx responses stop retries

Register the final URL: a 3xx is never followed, so an endpoint that answers 301/302 (an http → https upgrade, a trailing-slash redirect, a vanity host that forwards) fails every delivery. A 3xx or 4xx response (except 429) is NOT retried: treated as "this exact payload/config will never succeed," and the delivery is marked failed permanently. 410 Gone is stronger: it disables the ENDPOINT immediately. An endpoint also auto-disables after a sustained run of failed deliveries regardless of status code; re-enable it with PATCH /webhooks/endpoints/{endpointId}.

Verifying a delivery

Every delivery is a POST with a JSON body (the envelope) and three Standard Webhooks headers: webhook-id, webhook-timestamp, webhook-signature. Verify the signature with the secret returned exactly once, at creation (or the last rotation): see POST /webhooks/endpoints and POST /webhooks/endpoints/{endpointId}/rotate-secret. During a secret rotation's 24-hour overlap window, webhook-signature carries TWO v1,<sig> pairs (old and new secret). Validate against either.