Idempotence des webhooks de paiement: éviter les doublons en 2026

Le verdict en trois phrases

Les fournisseurs de paiement rejouent un webhook s'ils ne reçoivent pas votre 200 à temps: c'est voulu, et cela veut dire que le même événement arrivera plusieurs fois. Sans protection, chaque rejeu peut créer une seconde commande, un second email, un second débit de stock — voire un double crédit. La parade est l'idempotence: une clé unique (event_id) qui garantit qu'un événement n'est traité qu'une seule fois, quel que soit le nombre de rejeux.

Dédup applicative vs contrainte base

Deux stratégies existent. La déduplication applicative vérifie en mémoire/cache si l'ID a déjà été vu; la contrainte base pose un index unique sur event_id et laisse la base rejeter le doublon. La seconde est la plus sûre car elle résiste aux traitements concurrents.

Paramètres d'idempotence 2026

La clé d'idempotence est l'event_id fourni par Wave/Paystack. On la stocke avec un TTL, et sur réception d'un doublon on répond 200 sans re-traiter. Objectif: ne jamais dépendre du hasard du timing.

Bonne pratique: enveloppez l'insertion de la clé et le traitement métier dans une transaction unique. Si l'insertion viole la contrainte (doublon), on annule et on répond 200 — aucun effet de bord.

Un programme d'apporteurs pour financer ces chantiers

Ces sujets d'ingénierie paraissent techniques, mais ils se vendent: tout commerçant qui a déjà expédié deux fois ou crédité un client en double en comprend la valeur. Chez Kolonell, notre programme apporteur d'affaires rémunère quiconque nous recommande un projet — vous n'avez pas besoin d'être développeur, juste de connaître un besoin.

Exemple: un e-commerce Growth à 2 000 000 FCFA vous rapporte 12 % = 240 000 FCFA à la vente, plus 5 % sur la maintenance récurrente. Devenez apporteur en nous écrivant sur WhatsApp.

Mini cas pratique

Rokhaya, gérante d'une boutique en ligne à Dakar, a subi un pic réseau: 3 webhooks rejoués sur 400 paiements. Sans idempotence, cela a créé 3 commandes en double, 3 colis préparés en trop et 45 000 FCFA de stock immobilisé (panier moyen 15 000 FCFA). Après ajout d'une contrainte unique sur event_id avec TTL 72 h, les rejeux suivants renvoient 200 sans rien recréer: zéro doublon sur les mois suivants.

FAQ

Qu'est-ce qu'une clé d'idempotence ? C'est un identifiant unique par événement (event_id) qui garantit qu'un webhook rejoué produit exactement le même résultat qu'au premier passage: aucun doublon.

Pourquoi une contrainte base plutôt qu'un cache ? La contrainte unique résiste aux traitements concurrents: si deux rejeux arrivent en même temps, la base n'en accepte qu'un. Un cache seul peut laisser passer une course critique.

Quel TTL choisir ? 72 h, aligné sur la fenêtre pendant laquelle le fournisseur peut rejouer un événement. Au-delà, la clé peut expirer sans risque de nouveau rejeu.

Que répondre à un doublon ? Un code 200 (OK), sans re-traiter. Répondre autre chose pousserait le fournisseur à rejouer encore, aggravant le problème.

Quelle proportion de webhooks sont des rejeux ? En pratique 0,5 à 2 %, surtout lors de pics de latence ou de coupures réseau. C'est rare mais suffisant pour causer des doublons coûteux sans idempotence.

Discutons de votre projet. Nous rendons vos webhooks idempotents (contrainte base, TTL, transaction atomique) et vous pouvez aussi devenir apporteur d'affaires Kolonell. WhatsApp +221 77 596 93 33.