Flutterwave Webhooks: Retry, Timeout and Idempotency Done Right in 2026

The verdict in three sentences

A Flutterwave webhook is never guaranteed to be unique or on time: it can arrive twice, several minutes late, or get lost. Your code must therefore be idempotent (the same event processed twice changes nothing), patient (exponential-backoff retry) and covered (catch-up polling for lost events). On 10,000 events a month, about 2% arrive as duplicates and 0.3% get lost without a safety net — that is 30 payments vanishing if you have no polling.

The three failures to cover

A reliable webhook system never assumes the best case. It assumes every event can fail in three ways, and handles each.

The duplicate: the provider replays an event because your 200 arrived too late, and you receive the same confirmation twice. Without idempotency, you credit the order twice. The delay: a traffic spike on the provider side pushes delivery back several minutes; your system must not conclude failure too soon. The loss: the event never arrives (network failure on both sides); only backup polling recovers it.

These figures are a 2026 order of magnitude: they vary by provider and network quality, but the architecture must hold in the worst case.

The retry strategy and the polling fallback

When your server does not answer, the provider replays with exponential backoff: intervals lengthen so as not to drown a server already struggling. On your side, if you must replay internal processing (queue), apply the same logic.

Backoff alone is not enough: if the event is definitively lost, no retry will bring it back. That is why catch-up polling is essential. Every 15 min, a job lists orders in "pending" status for more than X minutes and queries the provider's status API directly. This double coverage — retry pushed by the provider, polling pulled by you — brings the real loss rate from 0.3% to nearly zero.

Mini case study

Fatou runs a booking platform in Lagos with Flutterwave. In April 2026, she processes 10,000 events. Without a net, she would have lost about 30 payments (0.3%) and double-credited about 200 orders (2%).

After setting up idempotency by transaction_id and polling every 15 min, the picture changes: the 200 duplicates are absorbed with no effect (same key = ignored), and of the 30 lost events, polling recovers 28 in under 15 min each. The 2 remaining are handled at the daily reconciliation. Result: zero double credit, two orders recovered by hand instead of thirty lost. Time spent on payment incidents drops from 4h to 20 min per week.

FAQ

How do you guarantee idempotency? Store each processed event's transaction_id in a table with a uniqueness constraint. Before any processing, check its presence: if it already exists, return 200 without doing anything. This neutralizes the 2% duplicates.

What polling interval should you pick? Every 15 min for orders pending more than 5 min is a good balance of freshness and load. More frequent polling burdens the provider API with no real gain.

How many retries before giving up? On the provider side, up to 5 attempts over about 35 min. Beyond that, rely only on polling: an event that has not arrived after 5 attempts is probably lost.

Should you process events in arrival order? No: process by event timestamp, not by reception order. About 1% of events arrive out of order, and trusting arrival creates status inconsistencies.

What do you do with an invalid-signature event? Immediate reject and security log. An invalid signature signals either a config bug or a forgery attempt: never process such an event.

Let's talk about your project. We build your Flutterwave webhook handling with idempotency, retry and polling so no payment is lost. WhatsApp +221 77 596 93 33.