Flutterwave webhooks: secret hash and retries
How a Nigerian business should check and answer Flutterwave webhooks, what happens when delivery fails, and what Achekam verifies first.
By Achekam · · 4 min read · For Running a business businesses in Nigeria
A webhook is a message Flutterwave sends to your system when something happens: a payment succeeds, a transfer completes. It is what lets an invoice turn from "unpaid" to "paid" without anyone refreshing a dashboard. When webhooks work, nobody notices them. When they fail, customers who have paid receive reminders, and staff start marking invoices paid by hand on the strength of screenshots.
The business owner does not need to write the code, but should know the rules well enough to ask the right questions of whoever does. This article sets out Flutterwave's documented rules for webhooks, and what Achekam checks before a Flutterwave payment reaches the books.
The secret hash header
Anyone who knows your webhook address can send a message to it. The secret hash is how you tell Flutterwave's messages from everyone else's. Flutterwave's documentation says that if a merchant sets a secret hash, Flutterwave includes it in a verif-hash header on each webhook. A request whose header is missing or does not match can be discarded as not coming from Flutterwave.
Set a secret hash, keep it private, and make sure your system checks it on every request. The same page advises against strict IP whitelisting for webhooks, because Flutterwave's IP addresses are dynamic, so the hash rather than the sender's address is the check to rely on.
Answer with a 200, quickly
Flutterwave needs to know the message arrived. Its documentation says a webhook endpoint must return a 200 HTTP status code to acknowledge receipt, and any other response code, including 3xx redirect codes, is treated as a failure. It also says webhook requests time out after 60 seconds, and a request the endpoint does not answer within that window is marked as failed.
The documentation recommends returning 200 at once and queueing any long-running work. In other words: acknowledge first, then process. A system that tries to update the invoice, send a receipt and post the ledger before replying risks running out of time on a busy day.
Retries, if you switch them on
Failures happen: a server restarts, a network drops. Flutterwave's documentation says that when webhook retries are enabled on the dashboard and no 200 status code is received, Flutterwave retries the webhook call 3 times with a 30-minute interval between attempts.
Note the condition: retries happen only when enabled. Check the setting on your dashboard. Without it, one failed delivery is the only delivery.
Re-query before giving value
A webhook tells you something happened. It is not, on its own, proof. Flutterwave's documentation says that before giving value to a customer on the strength of a webhook, the merchant should re-query the API to confirm that the transaction's status, amount, currency and tx_ref match what it expects. The same page recommends a background job that polls pending transactions, for instance every hour, in case the webhook endpoint fails.
Re-querying protects you twice over. It stops a forged message from marking an invoice paid, because the forger cannot change what Flutterwave itself reports. And it catches the honest mistake of a payment that started but did not finish, which can still produce a notification your system has to read correctly.
The same event can arrive twice
Flutterwave's documentation says the same webhook event may occasionally be sent more than once, so event processing should be idempotent, meaning that handling it a second time changes nothing, to avoid giving a customer value multiple times. A system that ships goods or credits an account each time a message arrives will one day ship twice.
All of these rules are on Flutterwave's webhooks page, which explains how to receive and verify notifications about payments and transfers before acting on them.
What Achekam does with a Flutterwave payment
If you take Flutterwave payments on Achekam invoices, Achekam is the system receiving the payment news, so its own checks matter.
- Your keys, your account. A workspace administrator enters the business's own Flutterwave credentials in Settings under Payment Gateways & Checkout, and can test the connection with a real call to Flutterwave. Non-administrators can view the settings but not save them.
- Re-verification. A business can take Flutterwave payments on its invoices in ZAR, NGN, KES, GHS or USD, and each payment is re-verified with Flutterwave before it is recorded, in line with Flutterwave's advice to re-query before giving value.
- No double payment. A verified payment is recorded as a receipt against the invoice, debiting the Flutterwave clearing account and crediting trade receivables. The amount is checked against what the link asked for, and a repeated notification never pays twice, which is the idempotent handling Flutterwave asks for.
One limit to know. Achekam's scheduled check that asks the provider about open payments, picking up a payment whose notification never arrived, is described for M-Pesa, Paystack and Pesapal. Flutterwave is not in that list for invoice payments. So for Flutterwave, switch on retries in the dashboard, and when a customer says they paid, look for the transaction in Flutterwave before marking anything by hand. Connecting a provider is described in setting up your payment gateway, and the Paystack equivalent in Paystack webhook set-up.
Questions to ask whoever runs your integration
- Is a secret hash set, and does every request get checked against it?
- Does the endpoint reply with 200 straight away and process afterwards?
- Are retries switched on in the Flutterwave dashboard?
- Is every payment re-queried for status, amount, currency and reference before the customer gets value?
- What happens if the same event arrives twice?
- Is there a job or a routine that catches payments whose webhook never arrived?
If any answer is "I'm not sure", that is the item to fix first.
General guidance only, not advice on your own circumstances. Tax and payroll rules change: check the current position with the authority or your adviser.
