Skip to content

Deduplicate repeated webhook deliveries with idempotency keys

Stop double-charging, duplicate Slack alerts, and twin CRM deals when SaaS platforms deliver the same webhook event two or three times.

Copy the prompt and paste it into the AI assistant you already use.

Four safeguards against duplicate webhook execution

  1. 01

    Extract or synthesize an idempotency key

    Use the vendor's unique delivery ID or hash stable business keys such as resource_id plus state transition.

  2. 02

    Acquire an atomic lock before processing

    Check and write the idempotency key atomically so two simultaneous deliveries milliseconds apart cannot both pass.

  3. 03

    Add debounce windows for chatty updates

    Hold rapid-fire user edits in a short settling window when reps save a CRM record five times in one minute.

  4. 04

    Pass idempotency headers downstream

    Forward deterministic Idempotency-Key headers to payment and ticketing APIs as a second layer of protection.

How it works in practice

Duplicate webhook burst (220ms apart)

10:04:11.100Z -> evt_8812 {"order_id":"ORD-441","status":"paid"} 10:04:11.320Z -> evt_8812 {"order_id":"ORD-441","status":"paid"}

Idempotent execution log

Delivery #1 (evt_8812): Lock acquired -> Fulfillment ticket #904 created. Delivery #2 (evt_8812): Duplicate key suppressed (200 OK acknowledged).

At-least-once webhook delivery turns into effectively-once business execution without dropping valid retries.

Common questions

Why do reliable SaaS providers send duplicate webhooks in the first place?

Most webhook senders use at-least-once delivery and retry automatically whenever network latency delays acknowledgment by even a few seconds.

What happens if the first workflow execution fails mid-run after locking the key?

Locks distinguish in-progress, succeeded, and failed states, releasing or re-running failed keys safely while blocking completed ones.

How is debouncing different from strict event deduplication?

Deduplication drops identical retried deliveries, whereas debouncing waits briefly to merge rapid sequential edits on the same record into one sync.

Learn more

Related guides and background articles for this task