The verdict in three sentences
A mobile money provider replays the same webhook several times: it is a feature, not a bug, meant to guarantee delivery. Without an idempotency key, each of these resends creates a duplicate order or a double charge, and 8 to 12% of webhooks are affected. The defense comes in three pieces: a key = the provider transaction ID, a deduplication table and a processing lock.
Why duplicates exist
Providers keep resending a webhook until they get a clear 2xx acknowledgement. If your server responds slowly, crashes mid-processing, or replies after the provider timeout, the provider treats the send as failed and replays. The result: the same payment arrives 2, 3, sometimes 4 times.
| Metric | Value (2026 estimate) | Impact |
|---|---|---|
| Duplicate webhooks observed | 8 to 12% | Phantom orders |
| Provider retry window | 24 to 72 h | Duration of risk |
| Resends per transaction | 2 to 4 | Duplicate multiplication |
| Double charges avoided with idempotency | 100% | The goal |
| Processing lock latency | < 50 ms | Negligible perf impact |
The idempotency pattern in three pieces
The recipe is simple and robust:
| Piece | Role | Technical detail |
|---|---|---|
| Idempotency key | Uniquely identify the transaction | = provider transaction ID |
| Deduplication table | Remember keys already processed | Unique insert, uniqueness constraint |
| Processing lock | Prevent two parallel handlers | Lock < 50 ms, released after |
| Key TTL | Purge after the risk window | 7 days |
The flow: when a webhook arrives, you try to insert its key into the deduplication table. If the insert succeeds, it is a new webhook and you process it. If it fails (key already present), it is a duplicate and you reply 200 immediately without doing anything. The database uniqueness constraint does all the work, even under heavy concurrency.
The 24-hour lock and the 7-day TTL
Two durations to tune carefully. The lock protects against two near-simultaneous resends (the provider can replay very fast): it lasts only as long as processing, usually under 50 ms. The idempotency key must stay in the database at least as long as the provider retry window, meaning 24 to 72 h; keep it 7 days for safety before automatic purge. Purging too early reopens the door to late duplicates.
Mini case study
Aminata runs an online fashion shop in Lagos that receives 1,500 mobile money payments per month. With a 10% duplication rate, that is 150 duplicate webhooks monthly. Without idempotency, some turn into phantom orders: stock wrongly decremented, notifications sent twice, sometimes a double charge to refund.
Need a professional website?
Kolonell builds websites that attract clients, optimized for the Sénégalese market. Free quote in 2 minutes.
Assuming only 1% of these duplicates generates a billed phantom order, meaning 15 incidents per month at an average basket of 20,000 FCFA, the financial and reputational risk reaches 300,000 FCFA monthly in refunds and disputes. With the unique-key + deduplication-table pattern, that figure drops to zero: each resend is recognized and ignored in under 50 ms.
FAQ
What proportion of webhooks is really duplicated?
Between 8% and 12% per our 2026 observations on major providers. On 1,500 payments that is about 150 resends to neutralize each month.
What value should I use as the idempotency key?
The provider transaction ID, which is stable and unique per payment. Never use your own order ID, because a customer can retry a payment for the same order.
How long should I keep the key in the database?
At least the provider retry window (24 to 72 h), ideally 7 days with an automatic TTL. Purging earlier reopens the risk of late duplicates.
Does the lock slow down payment processing?
No. A well-designed lock lasts under 50 ms, just long enough to insert the key. It is imperceptible to the customer and prevents parallel processing.
Does idempotency replace reconciliation?
No, the two are complementary: idempotency removes duplicates in real time, T+1 reconciliation catches residual cases and guarantees accurate books.
Let's talk about your project. We make your mobile money webhooks idempotent to eliminate 100% of duplicate orders. 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.
