The verdict in three sentences
A replayed payment webhook creates a double order, a lost one creates a phantom sale: both destroy trust and corrupt your accounting. The defence rests on three pillars — a mandatory idempotency key, HMAC signature verification, and a retry queue with reconciliation. In 2026, a serious mobile money checkout must absorb 2 to 5% duplicated webhooks and 0.3% lost ones without ever double-crediting or missing a sale.
Webhook incidents and their fix
Every aggregator sends asynchronous notifications. Without discipline they cause silent errors. Here are the typical 2026 cases and the correct technical response.
| Incident | Observed frequency | Consequence | Fix |
|---|---|---|---|
| Duplicated webhook | 2-5 % | Double credit / double order | Unique idempotency key |
| Lost webhook | 0.3 % | Unrecorded sale | Polling + reconciliation |
| Out-of-order (pending after paid) | 1-2 % | Inconsistent status | Timestamp + state machine |
| Invalid signature | rare | Possible fraud | Strict HMAC verification |
| Endpoint timeout | variable | Cascading retries | Respond < 5 s, async processing |
An idempotency key (often the provider's transaction ID) stored with a uniqueness constraint alone neutralises most duplicates.
Retries, signatures and timing
Aggregators replay webhooks until they receive a 2xx acknowledgement. Your settings must align with their policy.
| Setting | 2026 best practice | Reason |
|---|---|---|
| Expected HTTP response | 200 in < 5 s | Avoid needless retries |
| Retry policy | exponential up to 24 h | Absorb network outages |
| HMAC signature window | 5 min tolerance | Block late replays |
| Idempotency storage | 30-90 days | Cover late replays |
| Reconciliation | daily | Recover the 0.3% lost |
| Business processing | asynchronous (queue) | Respond fast, process later |
The golden rule: acknowledge fast, process slowly. Return 200 immediately, enqueue, then run the idempotent business logic.
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
Fatou, a developer for a store in Thiès, handles 800 orders per month. At 3% duplicated webhooks, that is 24 double notifications monthly. Before idempotency, 24 customers risked a double charge or double shipment; at a 15,000 FCFA average basket, monthly exposure reaches 360,000 FCFA of potential disputes. A simple uniqueness constraint on the transaction ID brings that risk to zero, for two hours of development.
FAQ
What is an idempotency key in practice? A unique identifier per transaction (often provided by the aggregator) that you store; if the same one arrives twice, you ignore the duplicate. It blocks 2 to 5% of replayed webhooks.
Why verify the HMAC signature? To guarantee the webhook truly comes from the aggregator and was not forged. Without it, an attacker could simulate a successful payment.
How long should I keep received webhooks? 30 to 90 days is enough to cover late replays and serve as an audit trail during reconciliation.
What about the 0.3% lost webhooks? Recover them via daily polling of the status API and a reconciliation that compares your orders to provider-confirmed transactions.
Is an endpoint timeout serious? Yes: if it exceeds 5 seconds, the aggregator retries, multiplying duplicates. Hence async processing after an immediate 200.
Let's talk about your project. We build idempotent, signed and reconciled webhooks for collection with no double credit or phantom sale. 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.
