Prevent Duplicate Records in CRM Using Webhooks and IdempotencyPrevent Duplicate Records in CRM Using Webhooks and Idempotency
The network for creativity
Join 1.25M professional creatives like you
Connect with clients, get discovered, and run your business 100% commission-free
Creatives on Contra have earned over $150M and we are just getting started
Here's a duplicate-record bug that arrives without an error and is nearly impossible to reproduce on demand.
You build a webhook handler that creates a deal in your CRM when a payment event fires. Testing is clean. In production, occasionally the same payment creates two records — same customer, same amount, a few minutes apart.
The cause: your payment processor retries on network timeout. If your handler takes a few seconds to respond (say it's chaining three downstream API calls), the processor assumes something went wrong and fires the same event again. Both runs succeed. Nothing in your logs looks wrong because nothing did go wrong — the handler worked exactly as written, twice.
The fix is two parts. Every incoming webhook event has an ID. Before writing anything, check whether you've already processed that ID — a key in your database or cache is enough. If it exists, return 200 and stop. If it doesn't, write it first, then proceed. That way a retry on the same event hits the check and exits cleanly.
The rule underneath it: a 200 acknowledges receipt, not uniqueness. Any webhook handler that creates or modifies state needs to treat duplicates as a given. The event ID is how you enforce idempotency.
Back to feed
The network for creativity
Join 1.25M professional creatives like you
Connect with clients, get discovered, and run your business 100% commission-free
Creatives on Contra have earned over $150M and we are just getting started