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.

ProviderResponse windowRetry behaviour
StripeRespond promptly with 2xxExponential backoff for up to three days in live mode
GitHub10 secondsNo automatic retries; redeliver manually or by API
Shopify5 secondsRetries with backoff; failing subscriptions can be removed
Slack3 secondsUp 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.

De-duplicating on the event ID
-- 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:

  1. Point the provider at a webhook.stream URL and set the response to 500. Watch the retries arrive and note their spacing and headers.
  2. Set a response delay longer than the provider's timeout to see how timeouts are reported.
  3. Replay one captured request against your handler twice with cURL and confirm the second run changes nothing.