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 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.
• 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 July 30, 2026