The verdict in three sentences
The number-one cause of "lost payments" is not payment failure but the webhook that never arrives or arrives twice. Without an idempotency key, a duplicate delivery (~1.5%) creates a second order; without retry, a delivery failure (1-3%) leaves the order pending. A reconciliation polling fallback recovers the ~4% of orders that would otherwise sit in limbo.
The anatomy of a reliable webhook
A robust webhook rests on four pillars: signature verification, idempotency, scheduled retry and a dead-letter queue.
| Pillar | Mechanism | 2026 order of magnitude |
|---|---|---|
| Signature | HMAC-SHA256 | Reject if invalid |
| Idempotency | Unique key per event | Duplicates ~1.5% |
| Retry | Exponential backoff | 5s / 30s / 2m / 10m / 1h -> 24h |
| Dead-letter | Persistent failure queue | Manual replay |
| Polling fallback | Periodic status query | Recovers ~4% |
HMAC-SHA256 verification guarantees the call really comes from the provider, not from an attacker faking a successful payment.
The transaction state machine
A mobile-money payment moves through precise states. Modeling these transitions avoids double confirmations and ghost refunds.
| State | Meaning | Possible transition |
|---|---|---|
| pending | Payment triggered | -> processing, failed |
| processing | Awaiting callback | -> success, failed |
| success | Confirmed and logged | -> reversed |
| failed | Failure or timeout | -> pending (retry) |
| reversed | Refunded / cancelled | final state |
Every transition must be idempotent: receiving the same success event twice must never confirm the order twice.
Need a professional website?
Kolonell builds websites that attract clients, optimized for the Sénégalese market. Free quote in 2 minutes.
Mini case study
Awa runs an online store in Dakar with 1,200 orders a month, average basket 20,000 FCFA. Before, with no polling fallback, about 4% of orders (48 a month) stayed stuck in "processing" although the customer had paid, nearly 960,000 FCFA of flows in limbo and dozens of support tickets. By adding an idempotency key and polling every 3 minutes, she cuts stuck orders below 0.3% and eliminates almost all "I paid but got nothing" complaints.
FAQ
Why verify the webhook signature? Without HMAC-SHA256 verification, anyone who knows your URL could fake a successful payment. The signature proves the call truly comes from the provider.
What is an idempotency key in practice? It is a unique event identifier you store before processing. If the same identifier returns, you ignore the duplicate instead of creating a second order.
What retry schedule should I use? An exponential backoff such as 5s, 30s, 2m, 10m, 1h then hourly up to 24h covers the vast majority of temporary network-side outages.
What is a dead-letter queue for? It keeps events that failed after all retries, for manual replay. Without it, those payments are lost for good.
Is polling enough on its own? It can act as a single safety net, but it is slower and heavier on API calls. The right design combines webhooks for speed and polling for the ~4% of missed cases.
Let's talk about your project. We build your webhook layer with idempotency, retry and a polling fallback so you never lose a payment again. 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.
