Le verdict en trois phrases
Les opérateurs mobile money renvoient volontairement plusieurs fois le même webhook (3 à 6 occurrences) pour garantir la livraison, ce qui expose toute intégration naïve au double-comptage. La parade n'est pas de faire confiance à l'ordre d'arrivée, mais de poser une clé d'idempotence et une table de déduplication à TTL. En 2026, entre 4 et 9 % des events sont des doublons — à un ticket moyen de 12 000 à 45 000 FCFA, chaque double-crédit évité est de l'argent réel sauvé.
Comportement des webhooks par opérateur (2026)
Ordres de grandeur 2026 pour dimensionner votre file de traitement.
| Opérateur | Occurrences même event | Fenêtre retry | Signature | Taux doublons |
|---|---|---|---|---|
| Wave | 3-5 | 24-48 h | HMAC | 4-7 % |
| Orange Money | 3-6 | 48-72 h | HMAC/token | 5-9 % |
| MTN MoMo | 3-6 | 24-72 h | HMAC | 4-8 % |
| Moov Money | 3-5 | 24-48 h | token | 4-7 % |
| Agrégateur PSP | 2-4 | 24 h | HMAC | 3-5 % |
Retenez : vérifier la signature HMAC doit prendre moins de 200 ms, et la fenêtre de retry impose une table de dédup dont le TTL couvre 30 à 90 jours pour absorber les retries tardifs.
Clé par event_id ou par référence commande ?
Le choix de la clé d'idempotence détermine la robustesse. Comparatif 2026.
| Critère | Clé par event_id | Clé par référence commande |
|---|---|---|
| Bloque les retries identiques | oui | oui |
| Bloque les events distincts d'une même commande | non | oui (attention aux légitimes) |
| Gestion remboursement partiel | facile | délicate |
| Risque de faux positif | faible | moyen |
| TTL table dédup | 30-90 jours | 30-90 jours |
| Recommandation | statut de paiement | réservation de stock |
La bonne pratique 2026 : clé par event_id pour la déduplication brute des webhooks, complétée par un verrou logique sur la référence commande pour l'effet métier (créditer, expédier). On ne mélange jamais les deux rôles.
Mini cas pratique
Seydou opère une boutique en ligne à Dakar : 400 commandes/jour, ticket moyen 22 000 FCFA. Orange Money renvoie en moyenne 4 fois chaque webhook, avec 7 % de doublons non filtres au départ. Sans idempotence, ~28 commandes/jour risquaient un double-crédit ou une double-expédition, soit ~616 000 FCFA/jour de valeur exposée. Après mise en place d'une table de dédup (clé event_id, TTL 60 jours) et d'un verrou par référence, le taux de double-traitement tombe à 0. Coût de l'incident évité sur un mois : plusieurs millions de FCFA de litiges et de stock expédié à tort.
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.
FAQ
Pourquoi les opérateurs renvoient-ils le même webhook ?
Pour garantir la livraison "au moins une fois" : si votre serveur ne répond pas 200 assez vite, ils rejouent l'event 3 à 6 fois sur 24 à 72 h. C'est un comportement normal à absorber, pas un bug.
Quelle clé d'idempotence choisir ?
Une clé par event_id pour la déduplication des webhooks, doublée d'un verrou par référence commande pour l'effet métier. Cette séparation évite à la fois les doublons techniques et les double-crédits.
Combien de temps garder la table de dédup ?
Un TTL de 30 à 90 jours couvre les retries les plus tardifs. En dessous de 30 jours, un retry tardif d'Orange Money (fenêtre jusqu'à 72 h, plus rejeux exceptionnels) peut repasser au travers.
Faut-il vérifier la signature HMAC à chaque fois ?
Oui, systématiquement, en moins de 200 ms. Un webhook non signé ou à signature invalide doit être rejeté avant même d'entrer dans la file de déduplication.
Comment gérer un remboursement partiel sans casser l'idempotence ?
Traitez le remboursement comme un event distinct avec son propre event_id, et appliquez l'effet métier via le verrou de référence commande. Ne réutilisez jamais la clé du paiement initial.
Discutons de votre projet. Nous concevons vos webhooks Wave, OM et MTN avec idempotence garantie et zéro double-crédit. 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.
