Building Reliable Mobile Money Payment Webhooks (2026)

The verdict in three sentences

A reliable webhook rests on three non-negotiable pillars: signature verification, idempotency and a retry queue. Without them, between 0.5% and 3% of payment notifications get lost — network, provider timeout (5 to 30 s), or a redeploy of your server. The golden rule: never trust the webhook alone, always back it up with a getStatus polling fallback.

The three pillars of a robust webhook

The signature guarantees the call really comes from the provider and not an attacker. Idempotency guarantees the same event received twice doesn't create two orders. Retry guarantees a temporary failure eventually succeeds.

The raw payload must be stored before any business logic: if your logic crashes, you can replay the event without re-querying the provider.

Retry, timeout and signature across providers

Respond 200 within 5 seconds, otherwise the provider treats the call as failed and retries. Heavy processing (email, stock, invoice) must move to an async queue.

Provider-side retry isn't enough: add your own queue with exponential backoff (1 s, 2 s, 4 s, 8 s…) for internal processing that fails after receipt.

The cost of a missed webhook

A payment confirmed on the customer side but never recorded on yours = a ghost order. The customer was charged, received nothing, opens a dispute. Cost: the refund OR free goods, plus support time (≈ 20 min), plus reputation. On 1,000 orders/month at 2% lost webhooks, that's 20 avoidable disputes.

Mini case study

Ibrahim runs a meal delivery service in Abidjan: 1,500 orders/month, basket 6,000 FCFA. He used to rely on the Wave webhook alone: ~1.8% lost, i.e. 27 orders/month paid but unconfirmed. Each cost ≈ 6,000 FCFA of free food + 20 min support. Monthly loss: 162,000 FCFA + 9 h. By adding idempotency + getStatus polling every 2 min on pending orders, he recovered 26 of 27: residual loss near zero.

FAQ

What does making a webhook idempotent mean? It means the same event received 1, 2 or 5 times produces the same result. You store the event's unique ID and ignore duplicates. Without it, a provider retry creates a double order.

Must I verify the signature on every call? Yes, always. Without verification, anyone knowing your URL can fake a successful payment. The signature (HMAC in 2026) authenticates the sender in a few milliseconds.

Why respond in under 5 seconds? Because most providers treat a response beyond 5-10 s as a failure and trigger a retry. Acknowledge first, do the heavy processing after, asynchronously.

Can a webhook really fail? Yes: 0.5% to 3% in 2026 depending on network and load. Hence the polling getStatus safety net on any order left pending beyond a few minutes.

How long should I keep the raw payload? At least 90 days for debugging and disputes, ideally 12 months for audit. Raw storage is cheap and saves hours of investigation.

Let's talk about your project. We build bulletproof Wave/Orange Money webhooks with idempotency and a polling fallback. WhatsApp +221 77 596 93 33.