Guide
Webhook Retries and Idempotency: Handling Duplicate Events
Webhook delivery is at-least-once. Providers would rather send an event twice than risk it not arriving, so duplicates are part of normal operation, not an edge case.
Why duplicates happen
From the provider's side, a delivery succeeded only if it received a 2xx response in time. If your server processed the event but the response was slow or lost, the provider cannot tell the difference between that and a failure. It sends the event again.
The usual causes:
- Your handler took longer than the provider's timeout, often only a few seconds.
- Your server returned an error after completing part of the work.
- A network fault dropped the response on the way back.
- A deploy restarted the process mid-request.
How providers retry
Schedules differ, but the shape is consistent: retry soon, then wait longer each time, then give up.
| Provider | Response window | Retry behaviour |
|---|---|---|
| Stripe | Respond promptly with 2xx | Exponential backoff for up to three days in live mode |
| GitHub | 10 seconds | No automatic retries; redeliver manually or by API |
| Shopify | 5 seconds | Retries with backoff; failing subscriptions can be removed |
| Slack | 3 seconds | Up to three retries over about five minutes |
Always confirm the current numbers in the provider's own documentation. They change.
Pattern 1: record the event ID
Every provider gives each event a unique ID. Store it when you process the event, with a unique constraint, and skip events whose ID is already present.
-- One row per processed event
CREATE TABLE processed_events (
event_id TEXT PRIMARY KEY,
processed_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
-- In the handler, inside the same transaction as the work itself:
INSERT INTO processed_events (event_id) VALUES ($1)
ON CONFLICT (event_id) DO NOTHING;
-- If no row was inserted, this is a duplicate: stop here.Doing the insert and the business change in one transaction is what makes this reliable. If the work fails, the marker rolls back with it and the retry is processed normally.
Pattern 2: make the operation naturally idempotent
Prefer operations that give the same result however often they run. "Set the order status to paid" is safe to repeat. "Add one to the paid-orders counter" is not. Upserts keyed on the provider's object ID are the workhorse here.
Pattern 3: fetch the current state
Treat the webhook as a signal that something changed, then ask the provider's API for the object's current state and store that. Duplicates and out-of-order events stop mattering, because you always write the latest truth. The price is an extra API call per event.
Ordering
Events can arrive out of sequence, especially around retries. If you apply payloads directly, compare a timestamp or version on the object and ignore anything older than what you already hold.
Test it before production does
You can rehearse all of this safely:
- Point the provider at a webhook.stream URL and set the response to
500. Watch the retries arrive and note their spacing and headers. - Set a response delay longer than the provider's timeout to see how timeouts are reported.
- Replay one captured request against your handler twice with cURL and confirm the second run changes nothing.