The verdict in three sentences
The front-end callback — the "payment successful" page shown to the browser — is trivial to forge and proves nothing: only the operator's signed webhook is authoritative. A reliable integration verifies the HMAC signature in under 5 seconds, stores the raw payload, deduplicates by transaction id and replays failed deliveries with exponential backoff 1/5/25s. Without these four guardrails, you fulfil unpaid orders and fulfil others twice.
The 4 non-negotiable guardrails
A mobile money webhook is only reliable if it resists forgery, duplicates, replay and network failures. Here is the checklist and 2026 targets.
| Guardrail | Role | 2026 target |
|---|---|---|
| HMAC signature | Prove the operator is the sender | Verify < 5s, else reject 401 |
| Idempotency | Prevent double processing | Dedupe by unique transaction id |
| Anti-replay | Block a replayed payload | Timestamp + 5-min window |
| Raw payload stored | Proof and reprocessing | Keep 100% before parsing |
Golden rule: treat the webhook as an order to validate, not a confirmation to display. The front-end triggers the UX; the webhook unlocks fulfilment.
Retry queue and dead-letter handling
Operators re-send webhooks when your server errors or responds too slowly. Without a retry queue on the operator side AND yours, a 30-second outage can lose a sale. Here are the parameters to configure.
| Parameter | 2026 order of magnitude | Why |
|---|---|---|
| Server response timeout | Respond < 3s (200 OK) | Avoid needless retries |
| Exponential backoff | 1s, 5s, 25s, 125s | Let the server recover |
| Attempts before dead-letter | 5 to 6 | Beyond that, human alert |
| Delivery failure alert | After > 3 consecutive failures | Warn before the loss |
| Payload retention | 90 days minimum | Reconciliation and disputes |
| Lost webhook rate | Target < 0.1% | Measured, not assumed |
Architecture tip: return 200 OK immediately after storing the raw payload, then process asynchronously via a queue. A webhook that waits for business processing to finish always times out on a peak day.
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
Ibrahim, who runs a restaurant in Abidjan, receives 90 orders a day via Wave and MTN. One Friday night his server saturates and takes 12s to respond: the operator replays 4 webhooks, triggering 4 double kitchen preparations (loss ≈ 18,000 FCFA). After a rebuild: 200 OK response in 0.8s, dedupe by transaction id, async processing. The next peak, 130 orders, no duplicates, no lost orders. The only incident — a webhook with an expired timestamp — is correctly rejected and logged.
FAQ
Why not trust the success page shown to the customer? Because it lives in the browser and can be replayed or forged in seconds. Only the operator's HMAC-signed webhook proves a payment truly happened.
What is idempotency in practice? It guarantees the same webhook received twice triggers only one fulfilment. You achieve it by deduplicating on the operator's unique transaction id before any processing.
How do I handle a traffic spike without losing payments? Return 200 OK in under 3s after storing the raw payload, then process on an async queue. The operator's 1/5/25s backoff covers micro-outages.
How long should I keep payloads? At least 90 days, for reconciliation and disputes. The raw payload is your evidence if a customer or operator contests a transaction.
When should a human be alerted? As soon as more than 3 consecutive delivery failures hit the same webhook, or when a message reaches the dead-letter queue after 5-6 attempts. Beyond that, every minute can cost a sale.
Let's talk about your project. We build signed, idempotent, bulletproof mobile money webhooks with retry queues and alerts. 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.
