Le verdict en trois phrases
Un webhook de paiement peut être livré plusieurs fois — c'est une garantie « at-least-once », pas « exactly-once ». Sans clé d'idempotence et table de déduplication, 2 à 5 % de doublons se transforment en doubles débits et litiges clients. La parade tient en trois éléments : clé unique, verrou transactionnel, réponse 200 systématique.
Pourquoi les doublons sont inévitables
Les opérateurs mobile money rejouent une notification tant qu'ils ne reçoivent pas un accusé de réception clair. Si votre serveur répond lentement, renvoie une erreur 500 ou expire, l'opérateur considère la livraison comme échouée et recommence. Votre code doit donc traiter chaque événement comme s'il pouvait arriver plusieurs fois.
| Comportement webhook 2026 | Valeur type | Conséquence sans idempotence |
|---|---|---|
| Taux de doublons observé | 2–5 % | Double facturation |
| Nombre de re-tentatives opérateur | jusqu'à 5x | Jusqu'à 5 débits |
| Délai entre re-tentatives | 1 → 30 min | Doublons différés |
| Réponse attendue | HTTP 200 | 500/timeout = rejeu |
| Fenêtre de dédup recommandée | 24 h | Doublons hors fenêtre |
La règle d'or : répondre 200 seulement une fois l'événement enregistré, jamais avant. Un 200 prématuré perd l'événement en cas de crash.
Le pattern d'idempotence
Chaque événement porte un identifiant stable fourni par l'opérateur (id de transaction ou id d'événement). On l'utilise comme clé primaire dans une table de déduplication. À la réception : on tente d'insérer la clé ; si elle existe déjà, on ignore et on répond 200 sans retraiter.
| Élément du pattern | Rôle | Détail d'implémentation |
|---|---|---|
| Clé d'idempotence | Identifier l'événement | id transaction opérateur |
| Table de dédup | Mémoriser le traité | contrainte UNIQUE sur la clé |
| Verrou transactionnel | Éviter la concurrence | SELECT ... FOR UPDATE |
| Log d'audit | Traçabilité | horodatage + payload brut |
| Réponse 200 | Stopper les rejeux | après commit uniquement |
| Fenêtre de rétention | Nettoyage | purge après 24–72 h |
Besoin d'un site web professionnel ?
Kolonell crée des sites web qui attirent des clients, optimisés pour le marché sénégalais. Devis gratuit en 2 minutes.
Deux webhooks identiques reçus en parallèle sont le vrai piège : sans verrou ou contrainte d'unicité en base, les deux passent le test « existe-t-il déjà ? » avant que l'un n'écrive. La contrainte UNIQUE côté base est votre dernière ligne de défense.
Mini cas pratique
Ibrahim tient une épicerie en ligne à Conakry avec 1 500 paiements par mois. Avec 4 % de doublons non gérés, ce sont 60 doubles débits mensuels. À un panier moyen de 12 000 FCFA, cela représente 720 000 FCFA à rembourser chaque mois, plus le coût des litiges et la perte de confiance. Après mise en place de l'idempotence, les doublons tombent à zéro : l'investissement d'une journée d'intégration est amorti en moins d'une semaine.
FAQ
Une contrainte UNIQUE en base suffit-elle ? Elle est indispensable mais pas suffisante seule : combinez-la avec un traitement transactionnel pour gérer proprement les webhooks concurrents et garantir un état cohérent.
Que renvoyer si l'événement est déjà traité ? Un HTTP 200. L'opérateur comprend que la livraison a réussi et arrête de rejouer. Renvoyer une erreur relancerait inutilement le cycle.
Combien de temps garder les clés ? Une fenêtre de 24 à 72 heures couvre la quasi-totalité des rejeux. Au-delà, on purge pour ne pas faire grossir la table indéfiniment.
Faut-il vérifier la signature du webhook ? Oui, systématiquement. L'idempotence évite les doublons ; la vérification de signature évite les faux événements malveillants. Les deux sont complémentaires.
Discutons de votre projet. On sécurise vos webhooks de paiement avec idempotence, verrou et log d'audit, testés contre les rejeux réels. WhatsApp +221 77 596 93 33.
Mohamed Bah
Fondateur, Kolonell
Passionné par le digital et l'entrepreneuriat en Afrique, Mohamed accompagne les entreprises sénégalaises dans leur transformation digitale depuis 2020. Fondateur de Kolonell, il croit que chaque PME mérite une présence en ligne professionnelle et accessible.
