Prompt
What causes duplicate webhook processing and how do I stop it?
Latest observation
Duplicate webhook processing usually happens because webhooks are designed to be at-least-once delivery, not exactly-once delivery. That means the sender may deliver the same event more than once, and your app may also process the same event more than once if retries or concurrency happen.
Common causes
-
Sender retries because it didn’t get a fast 2xx
- If your endpoint times out, returns a non-2xx, or is slow, the provider may retry.
- Even if your code processed the event, the provider may not know that.
-
Your endpoint processes too slowly
- If you do heavy work before responding, the provider may assume failure and resend.
-
Network or infrastructure issues
- Load balancers, restarts, dropped connections, or transient errors can make the sender retry.
-
Multiple deliveries of the same event
- Some providers intentionally resend events for reliability.
- Some events are duplicated by the provider itself.
-
Your own code reprocesses retries
- If you have queue consumers, workers, or multiple app instances, the same webhook payload may be handled more than once.
-
Missing idempotency / deduplication
- If you don’t store and check an event ID, each delivery looks new.
How to stop it
1) Make processing idempotent
Store a unique event identifier from the webhook payload or headers, and skip it if you’ve seen it before.
Typical approach:
- Extract
event_id - Check database/cache if already processed
- If yes, return 200 and do nothing
- If no, process and record it as processed
2) Acknowledge quickly
Return a 2xx response as soon as you’ve safely accepted the event, ideally after:
- verifying the signature
- storing the raw payload or event record
- enqueueing background work
Then do the real work asynchronously.
3) Use atomic deduplication
Don’t use a simple “check then insert” that can race under concurrency.
Use:
- a database unique constraint on
event_id - or an atomic cache operation like
SETNX - or transactional insert-and-process logic
4) Verify signatures
This won’t stop duplicates, but it prevents spoofed requests from being mistaken for real webhooks.
5) Design downstream actions to be idempotent too
Even if webhook handling is deduped, your side effects should also tolerate repeats:
- don’t create the same order twice
- don’t send the same email twice
- don’t charge the same card twice
6) Log and monitor retries
Track:
- event ID
- delivery attempt number
- timestamp
- processing status
This helps distinguish genuine duplicates from retries caused by errors.
Practical pattern
A robust pattern is:
- Receive webhook
- Verify signature
- Persist event with unique constraint on event ID
- If insert fails because it already exists, return
200 OK - Queue background job
- Return
200 OKimmediately - Worker processes event once
Example logic
Pseudo-code:
if not verify_signature(request):
return 401
event_id = request.json["id"]
try:
insert_into_events_table(event_id, raw_payload=request.body)
except UniqueConstraintViolation:
return 200 # already processed or accepted
enqueue_job(event_id)
return 200
Rule of thumb
Assume every webhook may arrive more than once. The fix is not “prevent duplicates at the source” so much as “make processing safe if duplicates happen.”
If you want, I can show you:
- a Node.js example
- a Python example
- a database schema for deduplication
- or how to handle this for a specific webhook provider like Stripe, GitHub, or Shopify