Skip to content
HookDeploy

Flutterwave webhooks

Last verified against Flutterwave's documentation on September 27, 2026.

On this page ↓

Flutterwave sends webhooks when a charge completes, a transfer settles, or a subscription changes. Two details catch people out. Retries are off unless you turn them on, and even then Flutterwave only retries 3 times, 30 minutes apart. And depending on your integration, the request is authenticated either with a static verif-hash header or with a flutterwave-signature HMAC of the body. This page covers both, how to fix the common errors, and where HookDeploy fits.

What Flutterwave sends webhooks for

AreaExample eventsTypical use
Chargescharge.completedGive value after a successful payment
Transferstransfer.completedTrack payouts
Subscriptionssubscription.cancelledKeep recurring billing in sync

Each webhook is a JSON POST with an event name and the transaction under data, including its id, tx_ref, amount, currency, and status.

How Flutterwave delivers webhooks

BehaviorDetail
Method and formatPOST with a JSON body
Authentication (v3)A verif-hash header containing the secret hash you set in the dashboard. It’s the same on every request, and doesn’t cover the body
Signature (newer integrations)flutterwave-signature: base64 HMAC-SHA256 of the raw body, keyed with your secret hash
Timeout60 seconds
Success200. Anything else, including 3xx, is a failure
RetriesOnly when enabled in the dashboard: 3 retries, 30 minutes apart
VerificationCall the verify transaction endpoint before giving value

Common Flutterwave webhook errors and how to fix them

Events lost during short outages

Retries are off by default. Turn them on in the dashboard, and even then, three retries 30 minutes apart cover about 90 minutes.

verif-hash offers little protection

The verif-hash value is the same on every request and doesn’t cover the body, so anyone who sees one request can forge others. Always confirm the transaction with Flutterwave’s verify endpoint, and use flutterwave-signature where your integration supports it.

Value given for the wrong amount

Check the fetched transaction’s status, amount, and currency against your order before giving value.

Redirects count as failures

Flutterwave treats a 3xx as a failure. Register the final URL your server serves.

CSRF middleware rejects the request

Frameworks like Rails and Django check POST requests for CSRF tokens. Exempt the webhook route.

Why use HookDeploy with Flutterwave

Stop depending on 90 minutes of retries

HookDeploy captures every Flutterwave webhook at Cloudflare’s edge and responds right away, before forwarding it to your server. Flutterwave’s short retry window stops mattering, because the event is already safe in HookDeploy.

  • Destination retries. Starter retries 3 times (after 30 seconds, 5 minutes, and 30 minutes). Pro and Scale retry up to 5 times on a schedule you choose. Free doesn’t retry automatically.
  • Incidents. Forward failures are grouped into incidents, and you can bulk-replay them once your server recovers.
  • History. HookDeploy keeps captured webhooks for your plan’s retention period, from 7 days on Free to 365 days on Enterprise.

One webhook, many systems

Send each Flutterwave event to your app, your accounting or ERP system, and an alert channel in parallel. A failing destination doesn’t hold up the others. Free includes 1 destination per endpoint, Starter includes 5, and Pro and above are unlimited.

Deliver to systems Flutterwave can’t reach

The HookDeploy Agent connects outward from your network over mTLS and delivers events to a local port, so a billing or fulfillment service in a private network can receive Flutterwave events with no public endpoint.

Develop against real events

A tap sends a temporary copy of live Flutterwave events to 127.0.0.1 on your machine while production keeps receiving them.

Know the limits

  • Transformations. A transformation changes the body, and then flutterwave-signature won’t verify at that destination.
  • Plan limits. On Free, requests beyond the monthly allowance or the daily limit get a 429, which Flutterwave treats as a failed delivery. Paid plans keep accepting traffic past the included volume.

Retries, replays, and duplicates

HookDeploy forwards the body and the verif-hash or flutterwave-signature header unchanged, so retries and replays authenticate like the original delivery. A privacy filter that changes the stored copy used for retries and replays breaks flutterwave-signature.

The same event can arrive more than once. Deduplicate on the transaction id, and confirm its status with the verify endpoint before giving value.

Set up Flutterwave with HookDeploy

  1. In HookDeploy, create an endpoint (for example, Flutterwave live) and copy its URL.
  2. On the Forwarding tab, add a destination pointing to your handler, or to an agent for private delivery, and set its retries.
  3. In the Flutterwave Dashboard, open Settings, then Webhooks, and set your HookDeploy URL and a secret hash. Turn on webhook retries.
  4. Make a test payment, and confirm the event appears in HookDeploy and reaches your handler.

Example handler (Node.js and Express)

import crypto from 'node:crypto';
import express from 'express';

const app = express();
const secretHash = process.env.FLW_SECRET_HASH;

function authentic(req) {
  const signature = req.get('flutterwave-signature');
  if (signature) {
    const expected = crypto.createHmac('sha256', secretHash).update(req.body).digest('base64');
    return signature.length === expected.length &&
      crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
  }
  const hash = Buffer.from(req.get('verif-hash') ?? '');          // v3: static value
  return hash.length === Buffer.byteLength(secretHash) &&
    crypto.timingSafeEqual(hash, Buffer.from(secretHash));
}

// Raw body parser on this route, registered before any global JSON middleware.
app.post('/webhooks/flutterwave', express.raw({ type: 'application/json' }), async (req, res) => {
  if (!authentic(req)) return res.status(401).send('Unauthorized');

  res.sendStatus(200);
  const event = JSON.parse(req.body.toString('utf8'));
  await enqueue({ name: event.event, transactionId: event.data?.id, txRef: event.data?.tx_ref });
  // Deduplicate on transactionId, then verify the transaction via the API before giving value.
});

FAQ

How do I verify a Flutterwave webhook?

For v3 integrations, compare the verif-hash header to the secret hash you set in the dashboard. Newer integrations send flutterwave-signature, a base64 HMAC-SHA256 of the raw body keyed with your secret hash. Either way, confirm the transaction with the verify endpoint before giving value.

Does Flutterwave retry failed webhooks?

Only if you enable retries in the dashboard. Then it retries 3 times, 30 minutes apart.

Why is verif-hash considered weak?

It's a static value that's identical on every request and doesn't cover the body, so it works like a shared password. Treat the webhook as a notification and confirm the transaction through the API.

What does Flutterwave count as a successful delivery?

Only a 200 response within 60 seconds. Any other status, including redirects, is a failure.

How do I deduplicate Flutterwave webhooks?

Use the transaction id in data, and make fulfillment idempotent on it.

Does HookDeploy break Flutterwave verification?

No. HookDeploy forwards the body and the verif-hash or flutterwave-signature header unchanged, so first deliveries, retries, and replays all authenticate.

Capture Flutterwave webhooks free

Start free