The verdict in three sentences
An unsigned payment webhook lets anyone fake a confirmation and trigger a delivery without paying. The combination HMAC SHA-256 signature + IP verification + idempotency key shuts that door and guarantees zero double-credit. Across 50,000 transactions a month, a single poorly secured webhook can cost several million FCFA in fraud and disputes.
The three lines of defence
Securing a webhook means stacking independent controls. If one falls, the others hold.
| Control | What it blocks | 2026 standard |
|---|---|---|
| HMAC SHA-256 signature | Forged payload | Signed header, shared secret |
| Source IP verification | Spoofed sender | Operator allow-list |
| Idempotency key | Double processing | Unique ID per transaction |
| Timestamp + tolerance | Request replay | 5-minute window |
| Strict HTTPS | Interception | TLS 1.2 minimum |
The HMAC signature is the central control: it proves the message truly comes from the operator and was not altered in transit.
Mechanism comparison by operator
Each operator has its method. A unified module must handle all of them.
| Operator | Verification method | Operator retry | Idempotency |
|---|---|---|---|
| Provider A | HMAC SHA-512 on body | up to 24 h | unique reference |
| Provider B | IP verification + signature | up to 24 h | idempotency-key |
| Provider C | Token + signed callback | up to 12 h | txn id |
| Stripe | Signature + timestamp | up to 72 h | event id |
The critical common point: all resend the webhook multiple times when in doubt. Without idempotence, each resend = an extra credit.
The 9-control checklist
Need a professional website?
Kolonell builds websites that attract clients, optimized for the Sénégalese market. Free quote in 2 minutes.
A production webhook must pass these nine points before being considered safe.
| # | Control | Required |
|---|---|---|
| 1 | HMAC signature verified | Yes |
| 2 | Source IP in allow-list | Yes |
| 3 | Idempotency key stored | Yes |
| 4 | Timestamp within window | Yes |
| 5 | Amount cross-checked with order | Yes |
| 6 | Transaction status confirmed via API | Yes |
| 7 | Fast 200 response (< 5 s) | Yes |
| 8 | Queue for async processing | Recommended |
| 9 | Immutable log of each event | Yes |
Mini case study
Sandrine, tech lead of an airtime top-up platform in Dar es Salaam, processes 50,000 transactions a month. Before hardening, a webhook without idempotence double-credited 1.5 % of operator retries, i.e. 750 duplicated transactions a month. At a 3,000 FCFA average basket, that was 2,250,000 FCFA of phantom credits to refund each month. After adding HMAC signature, the IP allow-list and the idempotency key, the double-credit rate fell to 0. The compliance work, estimated at 400,000 FCFA, was amortised in under a week.
FAQ
Is a signed webhook enough on its own? No. The signature proves origin, but without an idempotency key, the operator's multiple resends create duplicates. You need both, plus IP verification.
Why cross-check status via the API? Because a webhook can be delayed or lost. Confirming status with a direct API call ensures you only deliver on a truly completed payment, in 99.9 % of cases.
How long can an operator resend a webhook? Up to 24 hours for most, 72 h for Stripe. Your system must stay idempotent across that whole window.
Is a queue necessary? Strongly recommended above 10,000 transactions/month. It lets you return 200 immediately and process asynchronously, avoiding operator timeouts.
How much does securing a webhook cost? For an existing platform, budget 300,000 to 500,000 FCFA depending on the number of operators. ROI is immediate the moment one double-credit is avoided.
Let's talk about your project. We secure your payment webhooks with signature, idempotence and a queue. 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.
