Le verdict en trois phrases
Un webhook de paiement n'est jamais garanti unique : l'agrégateur peut le renvoyer 2 à 5 fois en cas de timeout ou de retry. Sans clé d'idempotence, votre système crédité la même commande plusieurs fois, expédie deux fois, ou fausse votre comptabilité. La parade tient en trois réflexes : vérifier la signature, stocker l'identifiant de transaction comme clé unique, et verrouiller le traitement.
Pourquoi les doublons arrivent
Les agrégateurs garantissent une livraison "au moins une fois", pas "exactement une fois". Si votre serveur répond lentement ou renvoie une erreur, l'agrégateur considère que le message a échoué et le rejoue. Votre code reçoit alors deux fois le même événement de paiement.
| Cause du renvoi | Fréquence relative | Conséquence sans idempotence |
|---|---|---|
| Timeout de votre serveur | Fréquente | Webhook rejoué 1-4 fois |
| Réponse HTTP non-200 | Fréquente | Retry automatique |
| Réseau instable | Moyenne | Livraison dupliquée |
| Maintenance agrégateur | Rare | Rejeu de lots |
| Bug applicatif (exception) | Variable | Double traitement |
L'ordre de grandeur observé : 1 à 3 % des transactions peuvent générer un doublon non géré si l'intégration ne protège pas le traitement.
Le pattern d'idempotence, concrètement
Le principe : chaque webhook porte un identifiant de transaction unique fourni par l'agrégateur. Avant de traiter, vous vérifiez si cet identifiant a déjà été traité. Si oui, vous répondez 200 sans rien faire ; si non, vous traitez puis enregistrez l'identifiant.
| Étape | Action technique | Effet |
|---|---|---|
| 1. Vérifier la signature | Comparer le HMAC avec votre secret | Rejette les faux webhooks |
| 2. Lire l'ID transaction | Extraire la clé unique du payload | Identifie l'événement |
| 3. Verrouiller la ligne | SELECT ... FOR UPDATE en base | Empêche le traitement concurrent |
| 4. Vérifier déjà traité | Chercher l'ID dans la table des paiements | Détecte le doublon |
| 5. Traiter une seule fois | Créditer, marquer payée, expédier | Action unique |
| 6. Répondre 200 vite | Acquitter pour stopper les retries | Coupe la boucle de rejeu |
Deux détails cruciaux : l'ID unique doit être contraint UNIQUE en base (la base devient le dernier rempart contre le doublon), et la réponse 200 doit être rapide pour éviter de déclencher de nouveaux retries.
Checklist d'intégration robuste
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.
Vérifiez la signature de chaque webhook (Wave, CinetPay, PayDunya ont chacun leur mécanisme). Utilisez l'identifiant de transaction de l'agrégateur, jamais votre propre numéro de commande, comme clé d'idempotence. Contraignez cet identifiant en UNIQUE. Verrouillez la transaction pendant le traitement. Répondez 200 immédiatement et faites les tâches lourdes en file d'attente. Loggez chaque webhook reçu, traite ou ignore, pour l'audit. Testez en rejouant volontairement le même webhook plusieurs fois.
Mini cas pratique
Moussa, développeur d'une boutique en ligne à Thiès traitant 3 000 commandes/mois, constaté des plaintes de clients facturés deux fois. Avant correction, environ 2 % des transactions, soit 60 commandes/mois, généraient un double traitement, pour un panier moyen de 25 000 FCFA : jusqu'à 1 500 000 FCFA de litiges et de remboursements potentiels chaque mois. Il ajoute une contrainte UNIQUE sur l'identifiant de transaction et un verrou en base. Après déploiement, les doublons tombent à 0, le support consacré aux litiges de double facturation disparaît, et la confiance des clients remonte. Coût : une journée de développement.
FAQ
Pourquoi recevoir deux fois le même webhook ? Parce que les agrégateurs garantissent une livraison "au moins une fois". En cas de timeout ou d'erreur de votre serveur, ils rejouent l'événement, parfois 2 à 5 fois.
Quelle clé utiliser pour l'idempotence ? L'identifiant de transaction fourni par l'agrégateur, pas votre numéro de commande interne. Contraignez-le en UNIQUE en base pour garantir un seul traitement.
La signature suffit-elle à éviter les doublons ? Non. La signature authentifie l'expéditeur mais ne dit rien sur le fait que l'événement a déjà été traité. Il faut combiner signature et clé d'idempotence.
Pourquoi répondre 200 rapidement ? Parce qu'une réponse lente ou en erreur déclenche un nouveau retry. Acquittez vite, puis traitez les tâches lourdes (e-mail, expédition) de manière asynchrone.
Comment tester mon idempotence ? Rejouez volontairement le même webhook plusieurs fois en environnement de test et vérifiez qu'une seule commande est créditée. C'est le test minimal avant mise en production.
Discutons de votre projet. Nous intégrons Wave, CinetPay et PayDunya avec idempotence, signature et retry gérés de bout en bout. 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.
