Step 1 · The pattern
The provider calls you
When a payment succeeds, the provider sends an event to your webhook. You mark the order paid, ship it, and reply 200 OK so the provider knows you got it.
- webhook event
- 200 OK
In short
Webhook dedupe: how it works and how it breaks
A payment provider tells you about events, such as a successful payment, by calling your webhook endpoint. If it does not get a quick 2xx reply, it assumes delivery failed and sends the event again. This is at-least-once delivery: you will get every event, and now and then you will get one twice. If your handler does real work for every delivery, a duplicate means a second shipment, email or credit. The fix has two parts. First, record each event's unique ID in a table with a unique constraint, in the same transaction as the work; if the insert fails you have seen it, so acknowledge and stop. Second, reply fast: verify the signature, store the event, return 200, and do slow work afterwards from a queue. Events can also arrive out of order, so re-fetch current state where you can.
How this comes up in interviews
"Your payment provider notifies you of successful payments by webhook. Design the handler so that an order is never shipped twice."
Then they ask
- Your handler crashes after doing the work but before recording the event ID. What happens on the resend?
- Events arrive out of order, for example a refund before the payment. How do you cope?
- Processing takes longer than the provider's timeout. How do you change the design?
A strong answer covers
- Delivery is at-least-once: every event arrives, and now and then one arrives twice.
- Store each event ID under a unique constraint, in the same transaction as the work.
- If the insert fails the event was seen before: acknowledge it and do nothing.
- Reply fast: verify the signature, store the event, return success, then do slow work from a queue.
- Events can arrive out of order, so re-fetch current state where you can.
Points to cover, not a script. Say them in your own words and tie them to a system you have worked on.
On one page: the track cheat sheet.
Sources: Stripe docs: handle duplicate webhook events ↗ · AWS Builders' Library: Making retries safe with idempotent APIs ↗ · Segment: Delivering billions of messages exactly once ↗ · Report a problem
Diagrams are our own simulations: the timings, rates and counts in them are illustrative, not measurements. Captions are original wording.