The verdict in three sentences
A badly handled payment webhook means 3% of orders double-credited in Lagos and missed confirmations when the provider retries. The fix rests on three pillars: signature verification to block fake calls, an idempotency key to process each event exactly once, and retries with backoff plus a dead-letter queue so no confirmation is ever lost. Done right, the double-credit rate drops to 0% and you stop shipping phantom orders.
The five classic webhook failures
A webhook is the provider (Paystack, Flutterwave, M-Pesa) knocking on your door to say "this payment is confirmed". If you open without checking who knocks, or count the same knock twice, everything derails.
| Failure | Root cause | Consequence | Fix |
|---|---|---|---|
| Double credit | no idempotency key | order x2, wrong stock | idempotency store |
| Fake payment | unsigned endpoint | fraud / spoofing | verify HMAC signature |
| Lost confirmation | unhandled timeout | order never validated | retry + dead-letter |
| Out-of-order events | events off-sequence | inconsistent status | timestamp + version |
| Malicious replay | no time window | replay attack | timestamp +/- 5 min |
Each row maps to a real incident we see in audits: the good news is that the fix is standard and testable.
The technical foundation to put in place
Here are the settings we configure by default. Providers retry for a long time (Paystack up to 72 h): your endpoint must be idempotent and respond fast.
| Mechanism | 2026 setting | Role |
|---|---|---|
| Idempotency store | key = event id, TTL 7 d | single processing |
| Signature verification | HMAC SHA-256, per-env secret | anti-spoofing |
| Anti-replay window | +/- 5 minutes | blocks replay |
| Retry backoff | 1s, 5s, 30s, 5min, 1h | absorbs outages |
| Dead-letter queue (DLQ) | after 6 failures | zero loss |
| Reconcile-on-read | fallback on load | safety net |
| Alert threshold | > 2% failures / 10 min | fast detection |
Need a professional website?
Kolonell builds websites that attract clients, optimized for the Sénégalese market. Free quote in 2 minutes.
Reconcile-on-read is the ultimate net: if a webhook is permanently lost, the app queries the provider when displaying the order and fixes the status.
Mini case study
Ibrahim runs a shop in Lagos, 1,200 orders/month, average basket NGN 45,000. Without idempotency, 3% (36 orders) were duplicated: stock over-decremented, customers re-credited, roughly NGN 1.6M of value churned in disorder each month. After the idempotency store, signatures and DLQ went live: 0 double credits over 90 days observed, and the 4-5 webhooks lost per month are auto-recovered by reconcile-on-read. Manual correction time: from several hours to zero.
FAQ
Why an idempotency key rather than a simple "already processed?" check? Because two identical webhooks can arrive in parallel: without an atomic stored key (7-day TTL), both pass the check at once. The key guarantees a single processing, even under concurrency.
How do you verify the signature without exposing the secret? The secret lives only in an environment variable, never in code. We recompute the HMAC SHA-256 of the received body and compare it to the header the provider sends.
What exactly does the dead-letter queue do? After 6 failed attempts (backoff up to 1 h), the event goes to the dead-letter queue for human inspection rather than being lost. That guarantees zero evaporated confirmations, even during a prolonged outage.
Do we rebuild everything if my site already exists? No: we add an idempotent webhook layer in front of your current logic. A typical hook-up takes 1 to 2 weeks, e2e tests included.
Let's talk about your project. We audit your payment endpoints and secure your webhooks before the next double-credit. WhatsApp +221 77 596 93 33.
Mohamed Bah
Fondateur, Kolonell
Passionate about digital and entrepreneurship in Africa, Mohamed has been helping Sénégalese businesses with their digital transformation since 2020. Founder of Kolonell, he believes every SME deserves a professional and accessible online présence.
