The verdict in three sentences
A Paystack webhook must be signature-verified, idempotent and protected by an exponential retry — otherwise a payment can be double-counted or spoofed. In Lagos in 2026, local collection runs around 1.5%, with automatic retries on failed deliveries. Settlement is typically T+1 for local transactions, which still demands strict server-side reconciliation.
The three pillars of a reliable webhook
In Node.js, you read the raw body, recompute the HMAC-SHA512 signature with your secret key, then store the transaction reference to reject duplicates. You respond 200 fast and process in the background.
| Pillar | Mechanism | Effect |
|---|---|---|
| Authenticity | HMAC-SHA512 on raw body | Rejects fake events |
| Idempotency | Unique key (reference) in DB | Prevents double-counting |
| Robustness | Exponential retry + queue | Absorbs redeliveries |
| Traceability | Timestamped log per event | Eases auditing |
| Fast response | Immediate 200, async work | Avoids timeouts |
Error codes and settlement delays
Paystack returns statuses you must map precisely so you never fulfil an order on a pending payment.
| Code / status | Meaning | Server action |
|---|---|---|
| success | Payment confirmed | Fulfil after idempotency |
| pending | Awaiting confirmation | Wait, do not fulfil |
| failed | Card/PIN declined | Mark failed, notify |
| reversed | Charge reversed | Roll back fulfilment |
| duplicate | Event already received | Ignore (idempotency) |
| settlement T+1 | Funds paid out | Reconcile with statement |
These values are a 2026 order of magnitude; exact labels depend on your merchant contract.
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
Chidi runs an online shop in Lagos collecting ₦3,000,000 per month via Paystack. Before hardening, an idempotency bug made him ship 12 duplicate orders in one month, roughly ₦180,000 lost. After adding a unique constraint on reference and signature verification, duplicates dropped to zero, with a stable collection cost near ₦45,000/month (~1.5%).
FAQ
Why read the raw body instead of parsed JSON? Because the signature is computed over the exact bytes received. If middleware reformats the JSON, the hash no longer matches and every check fails.
How do I guarantee idempotency? Store the reference with a unique constraint. On receipt, attempt the insert: if it fails on duplicate, respond 200 without reprocessing.
What should I do on a pending status? Nothing on the order side. Wait for a verified success event before fulfilling anything.
Why does settlement timing matter? A success status does not mean funds are available. Reconcile your successes daily against the settlement statement to catch discrepancies.
Let's talk about your project. We harden your Paystack webhook in Node.js with signature checks, idempotency and retries. 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.
