Webhook receiver best practices

Verify the raw body, answer within 10 seconds, deduplicate on webhook-id, drop stale changes with data.resource.sequence, pick status codes on purpose and rotate secrets with an overlap.

The delivery worker is built to be retried safely, which means your receiver will sometimes see the same delivery twice and must cope with it. These rules follow from how the worker actually behaves.

Verify before you parse#

Compute the signature over the bytes you received, not over JSON you parsed and serialised again: key order and spacing change the result. Reject a webhook-timestamp older than a few minutes. The verification page has code for Node.js, Python and Go.

Answer fast, work later#

The worker waits at most 10 seconds for your answer, then counts the attempt as failed. Store the body, answer 200, and do the slow work (updating your ERP, sending email) from your own queue.

Deduplicate on webhook-id#

webhook-id is the delivery's dlv_ identifier. It stays the same across automatic retries, a manual Resend and a bulk redelivery. Keep the ids you have processed and skip any you have seen. If several of your endpoints subscribe to the same event, each gets its own delivery; the event's id (wev_) is then the shared key.

javascript
app.post("/hooks/billing", express.raw({ type: "application/json" }), async (req, res) => {
  const valid = verifyWebhook(req.body.toString("utf8"), req.headers, process.env.WEBHOOK_SECRET);
  if (valid === false) return res.status(401).end();
  const deliveryId = req.headers["webhook-id"];
  if (await seen.has(deliveryId)) return res.status(200).end();
  const event = JSON.parse(req.body);
  const last = await sequences.get(event.data.resource.type, event.data.resource.id);
  if (event.data.resource.sequence > (last ?? 0)) {
    await jobs.enqueue(event);
  }
  await seen.add(deliveryId);
  res.status(200).end();
});

Use the sequence, not arrival time#

For one endpoint, deliveries about the same record are sent in order: a later one waits while the earlier one is still pending or held, and goes once that one succeeds, fails or is cancelled. Records do not wait for each other, and a held or resent delivery can still arrive after you have moved on. data.resource.sequence counts the events per record; ignore anything not newer than what you applied, or read the record from the API when you need its current state.

Choose your status code on purpose#

5xx, 408, 425 and 429 mean "try again later". Any other 4xx stops the delivery after two attempts and holds it as paused. 410 Gone pauses the whole endpoint and holds everything queued for it. Answer 410 only when you really want deliveries to stop.

Rotate secrets with an overlap#

bash
curl -sS -X POST "$BUSINESS_API/developer/webhooks/whk_2kP7vR3nXq9LmT4bW8cYzF1dHsJ/roll" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"overlap_seconds": 86400}'
json
{
  "id": "whk_2kP7vR3nXq9LmT4bW8cYzF1dHsJ",
  "tenant_id": "ten_2jR5wQ8nLm3KxT9vB6cYpZ1dHgF",
  "url": "https://erp.example.test/hooks/billing",
  "description": "ERP billing sync",
  "events": ["invoice.paid", "payment.received"],
  "enabled": true,
  "secret": "whsec_vQPM6Bhi6UrlK4RSGJDD11Kz8F6kc5T8pC/smJkBVPA=",
  "created_by": "usr_2mB4tK9qWx1RfZ7nLc3VhP8sDjE",
  "created_at": "2026-11-19T08:02:41.118204Z",
  "updated_at": "2026-11-19T11:40:03.551870Z",
  "previous_secret_expires_at": "2026-11-20T11:40:03.551870Z",
  "health": "healthy",
  "consecutive_failures": 0,
  "api_version": "v1"
}

Until previous_secret_expires_at, webhook-signature carries one v1, signature per secret, separated by a space, so a receiver holding either secret keeps accepting deliveries. Without a body the overlap is 24 hours; overlap_seconds goes from 0 (the old secret stops at once) to 604800 (7 days). In the dashboard this is Rotate secret.

Catch up after an outage#

Events stay readable for 90 days by default. GET $BUSINESS_API/developer/events accepts type, resource_type, resource_id, from and to, so you can compare what you stored with what happened.

Next steps#