Le verdict en trois phrases
Un webhook de paiement n'est jamais garanti unique ni à l'heure : entre 3 et 8 % arrivent en double ou avec plusieurs minutes de retard, selon l'opérateur et l'état du réseau. Sans clé d'idempotence, chaque doublon déclenche une double commande, une double expédition ou un double crédit. Quatre mécanismes — clé d'idempotence, file d'attente, signature HMAC et réconciliation par polling de secours — suppriment les commandes fantômes et rendent le checkout fiable à 99,9 %.
Pourquoi les webhooks doublent ou se perdent
Un opérateur qui ne reçoit pas votre réponse HTTP 200 assez vite réémet le webhook. Si votre serveur a traité l'événement mais répondu trop lentement, vous recevez le même paiement deux, trois, parfois cinq fois. Voici les ordres de grandeur observés en 2026.
| Opérateur | Taux de doublons estimé | Délai moyen de callback | Fenêtre de retry |
|---|---|---|---|
| Wave | 2-4 % | 1-3 s | 5 tentatives / 24 h |
| Orange Money | 4-7 % | 3-15 s | 4-6 tentatives / 24 h |
| MTN MoMo | 3-6 % | 2-10 s | 5 tentatives / 24 h |
| Moov Money | 4-8 % | 5-20 s | 4 tentatives / 12 h |
| Stripe | 1-2 % | < 1 s | 3 jours de retries |
Le piège classique : traiter le webhook de façon synchrone. Si l'expédition d'un e-mail ou l'appel à un autre service prend 6 secondes, l'opérateur a déjà renvoyé l'événement — et vous avez deux commandes.
Les quatre mécanismes à mettre en place
La règle d'or : répondre 200 immédiatement, traiter ensuite. Voici les quatre briques et le problème que chacune résout.
| Mécanisme | Problème résolu | Effet sur les commandes fantômes |
|---|---|---|
| Clé d'idempotence (ID transaction unique) | Doublons rejoués | -95 % |
| File d'attente + réponse 200 immédiate | Retries dus à la lenteur | -80 % des retries |
| Signature HMAC vérifiée | Faux webhooks / injection | Bloque 100 % des faux |
| Réconciliation par polling toutes les 15 min | Webhook jamais reçu | Récupère 100 % des perdus |
Concrètement : à chaque webhook, on lit l'ID de transaction de l'opérateur, on vérifie s'il est déjà en base ; s'il existe, on répond 200 et on ne fait rien d'autre. Sinon on l'enregistre, on répond 200, et on pousse le traitement dans une file. En parallèle, un job de réconciliation interroge l'API opérateur toutes les 15 minutes pour rattraper les paiements dont le webhook n'est jamais arrivé.
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.
Mini cas pratique
Ibrahim gère un site de vente d'électroménager à Abidjan : 1 200 commandes par mois. Avant idempotence, environ 5 % de doublons créaient 60 commandes fantômes par mois. Sur ces doublons, une dizaine partaient réellement en double expédition, à 40 000 FCFA de marchandise perdue chacune, soit 400 000 FCFA/mois de pertes, sans compter le service client.
Après mise en place de la clé d'idempotence et de la file d'attente, les commandes fantômes tombent à 0. Le job de réconciliation récupère en plus 12 paiements par mois dont le webhook s'était perdu, soit environ 480 000 FCFA de ventes qui étaient auparavant bloquées en "paiement en attente". Coût du chantier : un développement unique de 400 000 à 700 000 FCFA, amorti en moins de deux mois.
FAQ
Qu'est-ce qu'une clé d'idempotence concrètement ? C'est l'identifiant unique de la transaction renvoyé par l'opérateur, stocké en base avec une contrainte d'unicité. Si le même ID revient, on ignore le doublon. C'est le mécanisme qui supprime 95 % des commandes fantômes.
Pourquoi répondre 200 avant d'avoir tout traité ? Parce que l'opérateur réémet le webhook s'il n'obtient pas de réponse en quelques secondes. En répondant 200 immédiatement et en traitant dans une file, vous supprimez jusqu'à 80 % des retries inutiles.
La signature HMAC est-elle vraiment nécessaire ? Oui : sans elle, n'importe qui connaissant votre URL peut vous envoyer un faux "paiement confirmé". La vérification HMAC bloque 100 % de ces faux webhooks et ne coûte que quelques lignes de code.
Que faire si un webhook n'arrive jamais ? Un job de réconciliation par polling interroge l'API opérateur toutes les 15 minutes et rattrape les paiements manquants. Sur 1 200 commandes, il récupère typiquement une dizaine de paiements par mois qui seraient restés bloqués.
Combien de temps garder l'historique des webhooks ? Au moins 90 jours, pour tracer tout litige et rejouer un traitement au besoin. Un journal horodaté des webhooks reçus est votre meilleure preuve en cas de contestation d'un paiement.
Discutons de votre projet. On rend vos webhooks Wave, Orange Money et Stripe idempotents, signés et réconciliés — zéro commande fantôme. 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.
