# 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](/docs/webhooks/verify) 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

- [The retry schedule and endpoint health](/docs/webhooks/retries)
- [Test the receiver against the sandbox](/docs/webhooks/testing)
- [Upgrade notes for the Standard Webhooks headers](/docs/upgrades/2026-11-19-standard-webhooks)

