Setting up the Paystack webhook for your invoices
What Paystack expects of the webhook address that confirms invoice payments, how its signatures and retries work, and what Achekam does with each event.
By Achekam · · 4 min read · For Running a business businesses in Nigeria
Setting up Paystack on your invoices takes a few minutes, and most of it is obvious: paste in your keys, test the connection, send a pay link. One step looks like a technicality and is the one that matters most: copying a webhook address into your Paystack dashboard. Skip it, or paste it in the wrong place, and payments still reach Paystack, but your books may hear about them late, or only because something else went looking.
This article explains what a webhook is in plain terms, what Paystack's documentation expects of the address that receives one, how Paystack signs and resends its messages, and what Achekam does with each message when it arrives.
Why Paystack prefers webhooks
A webhook is a message Paystack sends to an address you give it, telling your system that something happened, typically that a payment succeeded.
The alternative is to rely on the customer's browser being sent back to your site after paying, known as a callback, or to keep asking Paystack whether anything has changed. Paystack recommends using webhooks rather than callbacks or polling, because callbacks can fail if the customer's network connection fails or is weak, or the device goes off after the transaction. A customer paying on a bus with a weak signal may complete the payment and never make it back to your page; the webhook still arrives.
Acknowledge at once, or it is sent again
Paystack's documentation says your webhook address must acknowledge each event by returning a 200 OK, otherwise the event is sent again for the next 72 hours. It advises returning the 200 OK immediately, before running any long tasks. The address must also be publicly available; a localhost address on someone's laptop cannot receive events.
The resending is generous. In live mode, Paystack resends an unacknowledged event every 3 minutes for the first 4 tries and then hourly for the next 72 hours. In test mode it retries hourly for 10 hours, with a 30-second timeout. Failed events can also be listed and resent through Paystack's Webhook Events API.
That persistence is helpful, and it has a consequence: your system will sometimes receive the same event more than once. Whatever receives it has to be able to tell that it already dealt with that payment.
The signature and the sending addresses
Anyone who knows your webhook address could send it a fake "payment succeeded" message. Paystack gives you two ways to tell real events from counterfeit ones.
The signature. Paystack's documentation says each event carries an x-paystack-signature header: an HMAC SHA512 signature of the event payload, signed with your secret key. You should verify it before processing the event. Only someone holding your secret key could have produced a valid signature.
The sending addresses. Paystack says it only sends webhooks from the IP addresses 52.31.139.75, 52.49.173.169 and 52.214.14.220, in both test and live environments, and that requests from other addresses should be treated as counterfeit.
Paystack explains acknowledgement, retries, signatures and its sending addresses on its webhooks documentation page.
Events arrive only for successful payments
Paystack's documentation says webhooks are the preferred way to confirm a transaction's status, but that Paystack currently sends webhook events only for successful transactions. An abandoned or failed attempt produces no webhook. That is why a webhook alone cannot be the whole story, and why a system that waits for news of failures will wait for ever.
What Achekam does with each event
In Achekam, a business can take Paystack payments on its invoices in NGN, KES, GHS, ZAR or USD, and each payment is confirmed with Paystack before it is recorded. The business pastes the webhook address Achekam provides into its Paystack dashboard. After that, each notification is handled in three layers:
- Signature check. The notification's signature is checked, so a message that did not come from Paystack is not trusted.
- Re-verification. Achekam then asks Paystack's verify API about the payment itself, rather than relying only on what the message said.
- Recording, once. A verified gateway payment is recorded as a receipt against the invoice, debiting the Paystack clearing account and crediting trade receivables, and the invoice shows as paid or part-paid. The amount is checked against what the link asked for, and a repeated notification never pays twice.
That last point answers Paystack's retries. If the same event arrives on the first try and again on the fourth, the invoice is still paid once.
Because the receipt lands in the same books as the invoice, the payment reaches your ledger as part of confirming it, with nothing to export.
Payments whose notification never arrived
Sometimes a webhook simply does not reach you: an address pasted wrongly, a configuration change, an outage somewhere along the way. For Paystack, as for M-Pesa and Pesapal, Achekam still picks up a payment whose notification never arrived, because the server asks the provider about open payments on a schedule and while the pay page is open.
That is a safety net, not a replacement for the webhook. Payments found that way arrive later than they would have, and a customer who paid and then sees "unpaid" on a reminder will be annoyed.
A set-up check
- Copy the webhook address from Achekam's payment gateway settings exactly, with no spaces.
- Paste it into the webhook field in the Paystack Dashboard for live mode, and separately for test mode if you test.
- Make a small live payment on a real invoice and confirm the invoice shows as paid promptly.
- If it does not, check the address before anything else.
- Recheck the address whenever someone changes the Paystack settings.
The full gateway set-up is in setting up your payment gateway, and the wider choices for naira collections are in collecting naira payments.
General guidance only, not advice on your own circumstances. Tax and payroll rules change: check the current position with the authority or your adviser.
