The verdict in three sentences
A mobile money provider replays its webhooks up to 5 times over 24 hours: without protection, each redelivery risks creating a ghost order or a double charge. Naive synchronous handling caps at 6 % duplicates and triggers timeouts beyond 30 seconds. A queue + idempotency key brings the duplicate rate below 0.05 % and always responds 200 in under 10 seconds.
Why a webhook is replayed (and why that's normal)
Providers guarantee "at least once" delivery, never "exactly once." If your server responds slowly, crashes, or returns anything other than 200, the webhook is redelivered. Your code must therefore handle the same event several times without ever producing two orders.
| 2026 parameter | Typical value | Consequence if ignored |
|---|---|---|
| Provider retry count | up to 5 times / 24 h | Duplicated orders |
| Retry window | exponential backoff over 24 h | Delayed duplicates |
| Required success code | 200 within 10 s | Automatic redelivery |
| Median webhook latency | 800 ms | Timeout on heavy processing |
| Idempotency key TTL | 72 h | Covers full retry window |
| Naive synchronous timeout | 30 s | Failure + redelivery |
Naive synchronous vs idempotent queue
The reflex is to do everything inside the webhook's HTTP request: verify the payment, create the order, trigger the payout, send the SMS. That is exactly what breaks under load.
| Criterion | Naive synchronous | Queue + idempotency |
|---|---|---|
| Duplicate rate | 6 % | < 0.05 % |
| HTTP response time | 2 to 30 s | < 300 ms |
| Retry resilience | None | Total (72 h TTL key) |
| Behavior under spike | Cascading timeouts | Absorbed by the queue |
| False payout risk | High | Near zero |
| Traceability | Weak | Log per key |
The recommended architecture in 5 points
- Receive the webhook, validate the signature, respond 200 immediately (< 300 ms).
- Extract the idempotency key (MoMo transaction reference) and check whether it already exists.
- If new, push the event onto a queue; if already seen, ignore and respond 200.
- A worker pops the event, creates the order, triggers the payout, sends the notification.
- Store the key for 72 h to cover the provider's entire retry window.
Mini case study
Ibrahim runs an online store in Kigali collecting 300 orders a day via MTN MoMo. With naive synchronous handling, 6 % of replayed webhooks created duplicates — 18 ghost orders a day. On a 15,000 FCFA average basket, that generated 270,000 FCFA of false entries to cancel manually every day, plus wrong payouts to suppliers. After moving to an idempotent queue, the rate fell to 0.05 % — fewer than one dubious order every six days — and his support team stopped losing 2 hours a day on corrections.
Need a professional website?
Kolonell builds websites that attract clients, optimized for the Sénégalese market. Free quote in 2 minutes.
FAQ
What is an idempotency key, concretely?
It is a unique identifier per event — the MoMo transaction reference. If two webhooks carry the same key, you know it is the same payment and you act only once. You keep it for 72 hours.
Why respond 200 before processing the order?
Because the provider redelivers if you exceed 10 seconds. By responding 200 in under 300 ms and then processing via a queue, you avoid the retry cascade and timeouts.
How many times can a webhook be replayed?
Up to 5 times over 24 hours with exponential backoff. Your 72-hour TTL comfortably covers that window.
Is a queue essential at low volume?
From a few dozen orders a day, yes: a single spike or slowdown is enough to trigger duplicates. The queue decouples receipt from processing.
How do I test idempotency before going live?
By deliberately replaying the same webhook 5 times: the system must create only one order and one payout. We provide a redelivery test set during integration.
Let's talk about your project. We design your MTN MoMo webhooks with a queue and tested idempotency. 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.
