Idempotent Paystack webhooks: preventing duplicate orders 2026

The verdict in three sentences

A payment webhook is replayed multiple times by design: Paystack and providers resend the same notification up to five times to guarantee delivery. Without an idempotency key, each replay recreates an order, generating 2-4% of duplicates that pollute stock and accounting. The fix rests on three pillars: verified HMAC signature, stored idempotency key, 24-hour dedup window.

The 6 critical events to handle

A webhook does not just say "paid." It carries a series of events, each triggering a different action in your system.

Ignoring any of these creates inconsistencies: a paid order left unvalidated, or stock blocked on a failed payment.

The idempotent status-and-action table

Idempotency means the same event processed twice produces exactly the same result. Here is how each status behaves on a replay.

The cost of a non-idempotent webhook

Here is what the absence of idempotency costs on a store handling 3,000 payments/month, average basket 14,000 FCFA-equivalent.

At 14,000 basket, 87 duplicates represent 1,218,000 FCFA-equiv. in transactions to cancel and refund each month, not counting support cost.

Mini case study

Ada sells clothing online in Lagos via card and transfer, 3,000 orders/month. Her webhook created an order on every replay: she processed 90 duplicates per month, i.e. 9 support hours and customers annoyed at being charged twice. Adding an idempotency key (the transaction reference) and 24-hour dedup, her duplicates drop to 3 per month. She recovers 8.5 hours and eliminates nearly all double-charge disputes.

FAQ

What is an idempotency key concretely? It is a unique per-transaction identifier (often the provider reference) you store on first processing. If the same identifier returns, you ignore the replay instead of recreating the order.

Why verify the HMAC signature? It proves the webhook truly comes from the provider, not a fraudster faking a payment. Without verification, anyone could validate an order for free.

How long to keep the dedup window? 24 hours covers nearly all provider replays, which span minutes to hours. Beyond that, late-replay risk is negligible.

What about an out-of-order event? A payment can arrive before its order creation. You queue the event and reorder by timestamp to avoid an inconsistent state.

Are failed webhooks replayed? Yes, if your server returns an error, the provider retries up to five times with increasing delay. Your endpoint should return 200 quickly, processing asynchronously if needed.

Let's talk about your project. We harden your payment webhooks with HMAC signature and idempotency to remove duplicate orders. WhatsApp +221 77 596 93 33.