Flutterwave webhook signature fails: verify the verif-hash header over the raw body

TL;DR

Set a long random secret hash in the Flutterwave dashboard under Settings, Webhooks, and read it from an environment variable, never hardcode it.

Steps

1. Do two things when wiring Flutterwave webhooks in Express. Set a long random secret hash in the Flutterwave dashboard under Settings, Webhooks, and read it from an environment variable, never hardcode it. Capture the raw body for the webhook route: use express.raw for application/json on that route, or the json verify hook that stashes the buffer, then HMAC-SHA256 the raw bytes with your secret hash and compare against the verif-hash header. Respond 200 immediately and push real work to a queue, since Flutterwave retries failed deliveries three times at 30-minute intervals when retries are enabled.

When to use

You are seeing this: Do two things when wiring Flutterwave webhooks in Express. Use this skill when you run into "Flutterwave webhook signature fails: verify the verif-hash header over the raw body".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

Source: Flutterwave engineering guide on dev.to ("What Are Webhooks, and How Do You Implement Them?"): documents two setup traps that break webhook verification. First, the secret hash is not automatic: you must set it yourself in the dashboard under Settings, Webhooks, in the Secret Hash field, and Flutterwave signs every webhook with it in the verif-hash header. Second, signature verification must run over the raw request body; standard express.json() parsing alters the body and makes the HMAC check fail even when everything else is right.

Verified resolution: Do two things when wiring Flutterwave webhooks in Express. Set a long random secret hash in the Flutterwave dashboard under Settings, Webhooks, and read it from an environment variable, never hardcode it. Capture the raw body for the webhook route: use express.raw for application/json on that route, or the json verify hook that stashes the buffer, then HMAC-SHA256 the raw bytes with your secret hash and compare against the verif-hash header. Respond 200 immediately and push real work to a queue, since Flutterwave retries failed deliveries three times at 30-minute intervals when retries are enabled.

Source URL: https://dev.to/flutterwaveeng/what-are-webhooks-and-how-do-you-implement-them-15j4