The verdict in three sentences
A webhook is the server-to-server call that confirms a payment: if it is not verified, an attacker can send a fake callback and trigger a free delivery. Two safeguards are non-negotiable: HMAC signature verification and idempotency, which prevents double credits (up to 1 to 2% of cases). Reply in under 5 seconds and keep logs for 90 days or more.
The four essential checks
A robust webhook stacks four defenses. Each blocks a specific attack or error.
| Check | Attack blocked | Implementation cost | Priority |
|---|---|---|---|
| HMAC signature | Fake callback | Low | Critical |
| Idempotency (unique ID) | Double credit | Low | Critical |
| IP allowlist | Requests outside PSP | Medium | High |
| Anti-replay (timestamp) | Replay of a real callback | Low | High |
| Statement verification | Phantom payment | Medium | High |
The HMAC signature compares a hash computed with the shared secret: if the hash does not match, the request is rejected before any processing.
Response and logging rules
Response behavior drives reliability. A badly answered webhook triggers retries and duplicates.
| Rule | 2026 target value | Why |
|---|---|---|
| Response time | < 5 s | Avoids PSP retries |
| Success code | Always 200 | Stops the retry queue |
| Async processing | Queue | Reply fast, process later |
| Timestamp tolerance | 5 min | Blocks late replay |
| Log retention | 90+ days | Proof and dispute debug |
| Deduplication | By transaction ID | 1-2% of duplicates avoided |
Best practice: acknowledge (200) immediately, then process the order in an async queue. Never block the response while a long task runs.
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 shop in Thies, gets a report: two customers were delivered without paying. Investigation: her endpoint accepted any POST without verifying the signature. A prankster had replayed a real callback. Fix in one day: HMAC verification (invalid signatures rejected), idempotency by transaction ID (the month's 2 duplicates vanish), and a 5-minute timestamp tolerance against replay. On 1,800 webhooks/month, she now blocks about ten suspicious requests and zero double credits. Cost: one day of dev, versus hundreds of thousands of FCFA of free merchandise avoided.
FAQ
What is an HMAC signature? It is a hash computed from the message body and a secret shared with the PSP. You recompute this hash on receipt: if it differs, the callback is fake and must be rejected before any processing.
Why is idempotency critical? Because PSPs sometimes resend the same callback (retry). Without deduplication by transaction ID, you credit the order twice in 1 to 2% of cases, distorting stock and accounting.
Do I need an IP allowlist? It is a good complement, but not enough alone since PSP IPs change. Combine it with the HMAC signature, which remains the primary defense.
How long should I keep logs? At least 90 days. They serve as proof in disputes, let you replay a task, and ease reconciliation of missing payments.
What if my webhook is slow? Reply 200 in under 5 seconds then process in an async queue. A slow endpoint triggers PSP retries and multiplies the risk of duplicates.
Let's talk about your project. We secure your payment endpoints with signature, idempotency and traced logs. 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.
