A webhook arrives twice and creates two CRM updates. Adding a delay between deliveries may make the problem rarer, but it does not establish whether the second event should change the customer record.
Deduplication needs a stable event or operation identity and a durable processing record.
Separate event identity from customer identity
The same customer can legitimately create several events. Do not deduplicate every update simply because the phone number or contact ID matches.
For a fictional integration, use the provider's stable event reference where available and scope it to the appropriate provider account or tenant. If a logical operation spans several events, define that relationship explicitly.
An event receipt might track the event reference, tenant, payload version or hash, processing state, result reference, and last error. Avoid storing unnecessary personal data just to recognise a repeat.
Claim work atomically before applying it
Two workers can receive the same event at nearly the same time. A separate “check if it exists” query followed by an unconditional insert can race.
Use the data store's appropriate uniqueness and transaction mechanisms. PostgreSQL's constraint documentation explains how database constraints enforce rules at the write boundary. The correct key depends on your event contract.
| Receipt state | Repeated-delivery behaviour |
|---|---|
| Complete | Return or recognise the existing result |
| Processing | Avoid starting competing work blindly |
| Failed before remote write | Retry under the defined policy |
| Remote outcome uncertain | Reconcile before issuing another change |
A unique receipt does not solve remote uncertainty
If the CRM accepts the update and your worker crashes before marking completion, the receipt may still say processing. That does not prove the CRM is unchanged.
Use a remote idempotency mechanism when supported, or a reconciliation strategy tied to the business operation. The uncertain-timeout guide explains this gap in more detail.
Also handle out-of-order events. A genuinely new delivery can contain older business state. Event deduplication and version ordering are separate protections.
Test repeats and crashes deliberately
Deliver one fictional event twice, deliver it concurrently, restart the worker after a remote success, and send an older update after a newer one. Inspect both the CRM record and receipt history.
Decide how operators replay failed work safely. A “retry” button should preserve the original event identity rather than generate a fresh identity that bypasses deduplication.
The trade-off is an extra operational store and cleanup policy. That cost is usually easier to reason about than trying to infer duplicates afterward from customer complaints.
Webhook deduplication questions
Is a payload hash enough?
Not always. Different valid events can have similar payloads, and equivalent events can differ in irrelevant fields.
Should we discard every repeated event immediately?
First inspect its processing state. The original attempt may need recovery.
What should the client see?
One intended CRM outcome and a traceable event history. Include those expectations in an integration brief.