Idempotent payment webhooks to avoid double charges in 2026

The verdict in three sentences

Payment providers replay a webhook if they don't get your 200 in time: it is by design, and it means the same event will arrive several times. Without protection, each replay can create a second order, a second email, a second stock deduction — even a double credit. The safeguard is idempotency: a unique key (event_id) guaranteeing an event is processed only once, no matter how many replays.

Application-level dedup vs database constraint

Two strategies exist. Application-level deduplication checks in memory/cache whether the ID was already seen; the database constraint puts a unique index on event_id and lets the database reject the duplicate. The second is safest because it withstands concurrent processing.

2026 idempotency parameters

The idempotency key is the event_id provided by Wave/Paystack. You store it with a TTL, and on receiving a duplicate you return 200 without reprocessing. Goal: never depend on timing luck.

Best practice: wrap the key insertion and the business processing in a single transaction. If the insert violates the constraint (duplicate), roll back and return 200 — no side effects.

A referral program to fund this work

These engineering topics look technical, but they sell: any merchant who has ever shipped twice or credited a customer twice understands the value. At Kolonell, our business-referral (apporteur d'affaires) program pays anyone who refers a project — you don't need to be a developer, just to know of a need.

Example: an e-commerce Growth project at 2,000,000 FCFA earns you 12 % = 240,000 FCFA on the sale, plus 5 % on recurring maintenance. Become a referrer by messaging us on WhatsApp.

Mini case study

Rokhaya, who runs an online shop in Dakar, hit a network spike: 3 replayed webhooks out of 400 payments. Without idempotency, that created 3 duplicate orders, 3 extra parcels prepared and 45,000 FCFA of stock tied up (average basket 15,000 FCFA). After adding a unique constraint on event_id with a 72 h TTL, subsequent replays return 200 without recreating anything: zero duplicates in the following months.

FAQ

What is an idempotency key? It is a unique identifier per event (event_id) guaranteeing a replayed webhook produces exactly the same result as the first pass: no duplicates.

Why a DB constraint rather than a cache? The unique constraint withstands concurrent processing: if two replays arrive at once, the database accepts only one. A cache alone can let a race condition slip through.

Which TTL should I choose? 72 h, aligned to the window during which the provider may replay an event. Beyond that, the key can expire with no risk of a further replay.

What should I return on a duplicate? A 200 (OK), without reprocessing. Returning anything else would push the provider to replay again, worsening the problem.

What share of webhooks are replays? In practice 0.5 to 2 %, mostly during latency spikes or network outages. It is rare but enough to cause costly duplicates without idempotency.

Let's talk about your project. We make your webhooks idempotent (DB constraint, TTL, atomic transaction), and you can also become a Kolonell business referrer. WhatsApp +221 77 596 93 33.