HTTP 200 is not exactly-once delivery: how do you handle duplicate webhooks?

[DimaGutierrez]

Your webhook times out. The receiver may already have processed it. What now?

Retrying can recover a missed delivery—or repeat a side effect. A successful HTTP response alone does not prove that an order, email or database update happened exactly once.

Reproduce the problem locally

Webhook Lab includes an example receiver. Run it with --fail-first 1, configure it as a named target, and replay the same captured event three times:

Attempt	HTTP result	Receiver outcome
1	503	Simulated failure
2	200	Processed
3	200	Deduplicated

Follow the complete setup. The receiver logs show the outcome. The workbench records all three delivery attempts.

The replay Idempotency-Key is the captured event ID. The example receiver performs deduplication in memory; restarting it loses that state. Capturing the same upstream payload again also creates a new event ID. Webhook Lab does not deduplicate incoming events or promise exactly-once processing.

Which design would you choose for a real receiver?

• A unique database constraint around a provider event ID?
• An idempotency record stored in the same transaction as the business change?
• A bounded deduplication window? How would you choose its duration?

Share one approach you use—or one failure case you are unsure how to handle. Include what happens if the process crashes between recording the key and applying the side effect. Pseudocode with fictional data is welcome.

This thread will help shape a durable receiver example. It is a design discussion, not a claim that the current prototype implements these guarantees.

También podés responder en español: ¿cómo evitás procesar dos veces un evento cuando hay reintentos?