Handling mobile money webhooks: idempotency and security 2026

The verdict in three sentences

A mobile money payment webhook is neither unique nor guaranteed: it may arrive 1 to 3 times depending on the provider, sometimes 10 seconds late. Reliability rests on two pillars: idempotency (dedup by reference) and signature verification (HMAC) to reject fake calls. Neglecting either exposes you to 3-5% duplicated orders or fraudulent confirmations.

Idempotency: dedup by reference

The principle is simple: each transaction carries a unique reference. On receiving the webhook, check whether that reference was already processed. If so, return 200 immediately without re-running business logic. Storage with a 24h TTL (Redis or a dedicated table) is enough because provider retries rarely span more than a day.

Resend behavior varies. MTN MoMo may call your callback twice, M-Pesa via Daraja retries on timeout, Airtel Money up to 3 times. Average webhook arrival latency after payment sits between 4 and 12 seconds in 2026.

Security and retry strategies

On security, always verify the signature on the raw request body, add an IP allowlist when the provider publishes one, and reject any unsigned call with 401. For reliability of YOUR downstream tasks (invoice, email, stock update), use a queue and exponential retry to absorb transient failures.

Mini case study

Grace, developer for an online grocery in Nairobi, collected 900 orders/month via M-Pesa and Airtel Money. A traffic spike caused timeouts and replayed webhooks: about 4.5%, or 40 orders/month, duplicated. After adding a 24h-TTL idempotency key and a queue with exponential retry (2s, 8s, 32s), the duplicate rate fell to 0.3%. Monthly support time on double-charge disputes dropped by about 12 hours, roughly KSh 30,000 of avoided cost.

FAQ

Why does a webhook arrive multiple times? Because the provider treats the call as failed if it doesn't get a fast 200. A slow response or a transient error triggers a resend: up to 3 times for Airtel Money, 5 for Paystack over 24h.

What should I store for idempotency? At minimum the processed reference and its status, with a 24h TTL. If the same reference returns, respond 200 without re-running the invoice, email or stock update.

How do I verify the signature correctly? Compute the HMAC over the raw received body before any JSON parsing, then compare in constant time. Re-serialized JSON breaks the signature and yields false 401s.

How long before I consider a payment lost? If no webhook arrives after 60 seconds, poll the verification endpoint (GET status). With normal latency of 4-12 seconds, 60 seconds leaves comfortable margin.

Do I need a queue for everything? No for the "order paid" write, which must be immediate and idempotent. Yes for downstream tasks (PDF, email, accounting sync) that benefit from exponential retry and a dead-letter queue.

Let's talk about your project. We harden your mobile money collection with idempotent webhooks, verified signatures and retry queues. WhatsApp +221 77 596 93 33.