The verdict in three sentences
A badly secured payment webhook is the leading technical cause of disputes: about 30 % of "I paid but the order isn't confirmed" complaints trace back to it. Four guardrails are enough: HMAC signature verification, idempotency key, exponential retry and logging. Without idempotency, 1 payment in 200 is processed twice, and each manual fix costs roughly NGN 2,600 in labour.
The four technical guardrails
A webhook is an inbound call from the payment provider to your server. Since anyone can try to hit that URL, it must be hardened.
| Guardrail | Role | Recommended setting |
|---|---|---|
| HMAC signature | Proves the call comes from the provider | Reject if signature invalid |
| Idempotency key | Stops processing the same payment twice | Key = transaction reference |
| Replay window | Blocks attacker-replayed calls | 5 minutes max |
| Exponential retry | Recovers missed webhooks | 3 attempts over 24 h |
| Timeout | Avoids blocking the provider | 10 s response max |
| Logging | Trace for disputes and audit | Keep 90 days |
The HMAC signature is non-negotiable: without it, a third party could fake a successful payment and trigger a shipment without paying.
The real cost of an unsecured webhook
A fragile webhook costs more than bugs: it costs time, customer trust and lost money. Here is the impact on an average store.
| Problem | Frequency without guardrail | Unit cost | Monthly impact (500 orders) |
|---|---|---|---|
| Double-processed payment | 1 in 200 | NGN 2,600 | ~NGN 6,500 |
| Paid order not confirmed | 1 in 100 | lost sale | ~5 lost sales |
| Customer dispute to handle | 30 % of disputes | NGN 2,600 | variable |
| Shipment without payment | rare but severe | product value | high risk |
| Manual reconciliation | daily | 1 h/day | ~30 h/month |
The heaviest line is often manual reconciliation time: up to 30 hours a month that a reliable webhook makes unnecessary.
Idempotency: the detail that kills duplicates
When a provider does not receive your response in time, it resends the webhook. Without an idempotency key, your server re-processes the payment: second confirmation, sometimes second shipment. By storing the transaction reference as a unique key, any repeated call is detected and safely ignored. It is the single line of code that prevents 90 % of duplicates.
Mini case study
Need a professional website?
Kolonell builds websites that attract clients, optimized for the Sénégalese market. Free quote in 2 minutes.
Ibrahim, a developer for a Lagos store, handles 500 orders/month. Before hardening, he saw ~2.5 duplicates/month (1 in 200) at NGN 2,600 each to fix, plus ~1 h/day of manual reconciliation, i.e. 30 h/month. After adding HMAC + idempotency + retry, duplicates fall to zero and reconciliation drops to ~2 h/month thanks to logging. Savings: NGN 6,500 in fixes and 28 hours recovered every month.
FAQ
Is HMAC signature really mandatory?
Yes. It is the only way to prove a call truly comes from Paystack or your provider. Without it, an attacker can fake a successful payment, risking an unpaid shipment.
How many retry attempts should I plan?
A classic scheme is 3 attempts over 24 h with increasing delays (e.g. 1 min, 15 min, 2 h). This recovers temporary network failures without hammering your server.
Why a 5-minute replay window?
It limits replay attacks: a webhook intercepted and resent later is refused if it exceeds 5 minutes. Beyond that, the call is treated as suspicious.
What if a webhook never arrives?
Add an active check: query the payment status API after 10 seconds, then via a retry queue. The webhook must never be the only source of truth.
How long should I keep logs?
At least 90 days. That is the useful window to arbitrate a customer dispute or reconstruct a contested payment.
Let's talk about your project. We secure your Paystack webhooks with signature, idempotency and retry tested in real conditions. 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.
