Le verdict en trois phrases
Un webhook de paiement n'est jamais garanti unique ni ponctuel : 3 à 7 % arrivent en double ou en retard. Sans clé d'idempotence, chaque doublon peut double-créditer une commande et fausser votre stock et votre comptabilité. Le bon pattern (clé unique, retry exponentiel, réconciliation nocturne) fait tomber les commandes fantômes de 2 % à moins de 0,1 %.
Pourquoi les webhooks trahissent sans protection
Les opérateurs mobile money renvoient les webhooks tant qu'ils ne reçoivent pas un accusé de réception 200. Une lenteur de votre serveur, et le même paiement est notifié plusieurs fois. Voici les problèmes typiques et leur fréquence 2026.
| Problème | Fréquence observée | Conséquence sans protection |
|---|---|---|
| Webhook en double | 3-7 % | Double crédit, stock fausse |
| Webhook en retard (> 30 s) | 4-9 % | Commande marquée échouée à tort |
| Ordre inversé (succès avant pending) | 1-3 % | Statut incohérent |
| Signature manquante ou invalide | 0,5-2 % | Faille de sécurité |
| Webhook jamais reçu | 1-2 % | Paiement encaissé non crédité |
Chacun de ces cas se traduit par une perte d'argent ou de confiance. La parade tient en trois mécanismes complémentaires.
Le pattern d'idempotence et de retry
La clé d'idempotence est un identifiant unique par transaction, stocké en base ; si le même identifiant revient, on ignore le doublon. Le retry gère les webhooks non reçus côté émetteur. Voici la file de retry recommandée.
| Tentative | Délai après échec | Action |
|---|---|---|
| 1 | Immédiat | Traitement + réponse 200 |
| 2 | 1 seconde | Retry si pas de 200 |
| 3 | 5 secondes | Retry |
| 4 | 30 secondes | Retry |
| 5 | 5 minutes | Retry, puis alerte |
| Nuit | Réconciliation | Rapprochement avec l'API opérateur |
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.
Ajoutez une vérification de signature HMAC et une fenêtre anti-rejeu de 5 minutes sur l'horodatage : tout webhook plus ancien est rejeté, ce qui bloque les attaques par rejeu.
Mini cas pratique
Ibrahim gère un site de vente de tickets à Dakar qui traite 3 000 paiements par mois. Avant, environ 2 % des commandes étaient fantômes (doublons ou statuts incohérents), soit 60 commandes à corriger manuellement, chacune coûtant 15 minutes de support. Après mise en place de la clé d'idempotence et de la réconciliation nocturne, il tombe à moins de 3 commandes problématiques par mois. Il économise près de 14 heures de support mensuel et supprime les remboursements pour double crédit.
FAQ
Ou stocker la clé d'idempotence ? Dans une table dédiée avec contrainte d'unicité sur l'identifiant de transaction opérateur. La base rejette nativement tout doublon, ce qui rend le traitement sûr.
Que faire d'un webhook en retard ? Ne jamais annuler une commande sur le seul silence d'un webhook. La réconciliation nocturne interroge l'API opérateur pour statuer définitivement sur les cas en attente.
Comment vérifier la signature HMAC ? Recalculez le hash du payload avec votre secret partagé et comparez-le à l'en-tête reçu, en temps constant. Ajoutez une fenêtre de 5 minutes sur l'horodatage contre le rejeu.
À quelle fréquence lancer la réconciliation ? Une passe nocturne suffit pour la plupart des boutiques, plus une passe horaire aux heures de pointe. Elle rattrape les 1 à 2 % de webhooks jamais reçus.
Discutons de votre projet. On audite votre tunnel de webhooks et on installe idempotence, retry et réconciliation pour éliminer les commandes fantômes. 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.