Run webhooks in production

The webhooks section covers the basics; this is the production checklist.

The contract

• Delivery is at-least-once and unordered. Dedupe by event id and treat data.object as the fresh current state, not a diff.
• Respond 2xx fast (enqueue, then process). Timeout is 10s.
• Retries: 1m → 5m → 30m → 2h → 12h, then the delivery is failed.
• After 20 consecutive failures the endpoint is auto-disabled. You'll see it in Settings → Developers → Webhooks (re-enable after fixing).

Verify every delivery

Check X-Nembol-Signature (t=…,v1=…, HMAC-SHA256 of <t>.<raw body> with your endpoint secret). Full code is in Verify signatures. During a secret rotation both old and new signatures are sent for 24h.

Gotchas

• Use the raw request body for the HMAC. Any re-serialization breaks the signature.
• Missed a window? Failed deliveries can be re-sent from the dashboard (Webhooks → deliveries → Redeliver), and GET /events is your backfill: events are kept 30 days.
• Endpoints must be HTTPS on a public host: a domain name (no IP address, no localhost, *.localhost, *.local or *.internal) that resolves to a public address. A name resolving to a private or internal address is refused at delivery time (the attempt fails).
• Test first: the dashboard's Send test event hits your endpoint with a signed dummy. Wire the signature check before going live.

Last updated on October 18, 2026