Design a webhook receiver that tolerates duplicate events

Webhook delivery is commonly at least once. A provider retry after timeout must not create another order, payment or message.

Deduplicate fixture events

The integration lab receives E1 twice.

from integration_cases import webhook_case

result = webhook_case()
assert result["responses"] == ["processed", "duplicate", "processed"]
assert result["effects"] == {"E1": 10, "E2": 20}
assert result["processed_count"] == 2
assert result["signature_verified_fixture"] is True
assert result["network_called"] is False

Verify signature over the exact raw body, timestamp tolerance and expected source before parsing. Store provider event ID with a uniqueness constraint in the same transaction as accepted work, or use an inbox table. A duplicate returns the stored state.

Acknowledge quickly after durable acceptance and process asynchronously. Handle out-of-order events by version/time rules. Keep signature secrets out of logs and rotate them with overlap.

The FDE for Freshers course uses webhook idempotency in its integration core.

Exercise

Send one signed fixture event twice and one tampered event. Prove the effect count is one and the invalid signature is rejected before parsing.

Continue learning

This article is part of the FDE integration and deployment foundations sequence. Use the neighbouring tasks when you need the prerequisite or the next application.

• Review the prerequisite or neighbouring task in Connect an application to a database safely.
• Continue with Implement bounded retries with backoff and jitter.

Reference: Standard Webhooks specification.