Idempotence des webhooks paiement : éviter les doubles encaissements en 2026

Le verdict en trois phrases

Un webhook n'est jamais envoyé une seule fois : Wave, Paystack ou Flutterwave peuvent retenter le même événement jusqu'à 5 fois sur 24 heures. Sans clé d'idempotence côté base de données, votre système livre la commande deux fois ou remboursé deux fois, et chaque doublon coûte une marge produit perdue. La solution tient en trois briques : une clé unique par événement, une table de déduplication, et un upsert atomique qui rend l'opération rejouable sans effet de bord.

Pourquoi les doublons arrivent

Un webhook est un appel HTTP. Si votre serveur répond lentement, plante, ou renvoie une erreur réseau après avoir traité l'événement, l'opérateur considère l'envoi comme échoué et retente. Vous avez donc déjà livré, mais vous recevez le même événement une deuxième fois.

Ces chiffres sont des ordres de grandeur 2026. Le point commun : tous retentent. Votre code doit partir du principe que chaque événement arrivera plusieurs fois, et se comporter comme si c'était la première.

Événement, risque et garde-fou

Voici la matrice à graver dans votre architecture. Pour chaque type d'événement, un risque de doublon et le garde-fou qui l'annulé.

Le pattern universel : chaque webhook porte un identifiant unique (event id ou transaction référence). Vous l'insérez dans une table processed_events avec une contrainte d'unicité. Pseudo-code SQL : INSERT INTO processed_events (event_id, processed_at) VALUES ($1, now()) ON CONFLICT (event_id) DO NOTHING RETURNING event_id;. Si l'insert renvoie une ligne, c'est la première fois : vous traitez. S'il ne renvoie rien (conflit), l'événement est déjà traité : vous répondez 200 sans rien faire. L'atomicite de l'upsert évite même les courses entre deux callbacks simultanés.

Mini cas pratique

Fatou, gérante d'une marketplace artisanale à Thiès, versait automatiquement les vendeurs à réception du webhook payout. Un vendredi, un pic de latence à fait retenter Flutterwave 3 fois sur les mêmes commandes. Sans clé d'idempotence, son système a versé 3 fois à 14 vendeurs. Sur un panier moyen de 25 000 FCFA et une commission plateforme de 10 %, chaque commande reverse 22 500 FCFA au vendeur. Les 28 versements en trop (2 doublons x 14 vendeurs) représentaient 630 000 FCFA sortis à tort, à récupérer un par un. Après ajout d'un ledger avec clé de transaction unique et upsert atomique, les doublons sont tombés à zéro. Le correctif a pris une demi-journée.

FAQ

Combien de fois un webhook peut-il être renvoyé en 2026 ?

Jusqu'à 5 fois sur 24 heures chez Wave, Paystack et Flutterwave, avec un backoff exponentiel. Votre code doit traiter chaque événement comme s'il pouvait arriver plusieurs fois.

Quelle est la clé d'idempotence à utiliser ?

L'identifiant unique de l'événement ou la référence de transaction fournie par l'opérateur. Vous la stockez avec une contrainte d'unicité en base pour bloquer tout retraitement.

Un doublon coûte-t-il vraiment cher ?

Oui. Un double fulfillment perd une marge produit, un double remboursement ou un double payout sort de l'argent réel. Dans l'exemple ci-dessus, 630 000 FCFA versés à tort en un seul incident.

Dois-je répondre 200 même si l'événement est un doublon ?

Oui. Répondez 200 pour dire à l'opérateur que vous avez reçu, sinon il retentera encore. Simplement, en interne, vous ne rejouez pas le traitement.

Un upsert suffit-il contre deux callbacks simultanés ?

Oui, si l'upsert est atomique avec une contrainte d'unicité (ON CONFLICT DO NOTHING). La base arbitre la course : un seul insert gagne, l'autre est ignoré proprement.

Discutons de votre projet. On rend vos webhooks paiement idempotents et on protège votre caisse des doubles encaissements. WhatsApp +221 77 596 93 33.