Le verdict en trois phrases
Un webhook de paiement peut arriver deux fois, en retard, ou dans le désordre — c'est normal, et votre système doit le supposer. La seule défense fiable est une clé d'idempotence (le transaction_id de l'opérateur) stockée dans une table d'événements, plus une fenêtre de réconciliation quotidienne qui rattrape les callbacks perdus. Sans ces deux garde-fous, vous aurez tôt ou tard un double débit ou une commande validée sans encaissement.
Pourquoi un webhook se rejoue (et ce que ça coûte)
Wave et Orange Money renvoient un callback tant qu'ils n'ont pas reçu un 200 OK de votre serveur. Un timeout de votre côté, un déploiement pendant la requête, un pic de charge — et le même événement repart. Sans déduplication, chaque relivraison ré-exécute votre logique métier : crédit du solde vendeur, envoi du SMS, validation de commande.
| Incident 2026 (ordre de grandeur) | Fréquence observée | Conséquence sans idempotence |
|---|---|---|
| Webhook livré en double | 0,3 à 1,5 % des paiements | Double crédit / double commande |
| Webhook en retard (> 5 min) | 1 à 3 % | Commande "non payée" à tort |
| Re-livraison différée | jusqu'à 24 h | Écart de caisse en fin de journée |
| Callback jamais reçu | 0,1 à 0,5 % | Paiement encaissé, commande bloquée |
| Signature invalide / falsifiée | rare mais critique | Fraude si non vérifiée |
L'écart typique détecté au rapprochement quotidien, avant automatisation, se situe entre 0,2 et 0,8 % du volume — soit 16 000 à 64 000 FCFA d'écart pour 8 000 000 FCFA encaissés.
Le patron technique : signature + table d'événements + retry
Trois couches, dans l'ordre. D'abord, vérifier la signature HMAC du header avant tout traitement — un callback non signé est jeté. Ensuite, insérer l'événement avec le transaction_id en contrainte unique : si l'insertion échoue (doublon), on répond 200 sans rejouer la logique. Enfin, un retry exponentiel côté sortant (paiement des vendeurs, notifications) : 3 tentatives, de 5 s à 15 min.
| Paramètre | Valeur recommandée 2026 | Raison |
|---|---|---|
| Clé d'idempotence | provider + transaction_id | Unique par opérateur |
| Réponse succès | 200 immédiat, traitement async | Évite le re-trigger |
| Tentatives retry sortant | 3 | Au-delà, alerte manuelle |
| Backoff | 5 s → 1 min → 15 min | Absorbe les pannes courtes |
| Fenêtre de réconciliation | quotidienne (T+1 matin) | Rattrape les callbacks perdus |
| Rétention table événements | 90 jours minimum | Audit et litiges |
La réconciliation quotidienne interroge l'API getStatus de chaque opérateur pour toute transaction restée pending au-delà de 48 h, et compare avec le relevé. C'est elle qui transforme un incident silencieux en ligne corrigée.
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
Fatou gère une boutique en ligne à Dakar, 900 commandes par mois, panier moyen 12 000 FCFA. Un mardi, un déploiement provoque un timeout pendant 4 minutes : 7 webhooks Wave sont relivrés. Sans idempotence, 7 commandes auraient été créditées deux fois côté vendeur, soit 84 000 FCFA d'écart. Avec la contrainte unique sur transaction_id, les 7 relivraisons répondent 200 sans effet, et le rapprochement du lendemain confirme 0 écart. Coût de la mesure : une colonne indexée et 20 lignes de code.
FAQ
Faut-il vraiment vérifier la signature du webhook ? Oui, sans exception. Un endpoint public non signé peut recevoir de faux callbacks "paiement réussi". La vérification HMAC coûte quelques millisecondes et bloque cette fraude à 100 %.
Que faire d'un paiement encaissé mais dont le webhook n'arrive jamais ? C'est le rôle de la réconciliation : on interroge getStatus pour chaque pending > 48 h. Sur 0,1 à 0,5 % des paiements, ce filet rattrape des commandes qui seraient restées bloquées.
Le retry peut-il provoquer un double débit côté client ? Non si le retry porte sur vos actions sortantes (payout vendeur, SMS), pas sur le débit client déjà réalisé par l'opérateur. Le débit est unique par transaction_id.
Combien de temps garder la table d'événements ? 90 jours minimum, idéalement 12 mois pour les litiges. Une transaction contestée peut remonter plusieurs semaines après l'encaissement.
Wave et Orange Money ont-ils la même fiabilité de webhook ? L'ordre de grandeur est comparable (0,3 à 1,5 % de doublons), mais les délais de re-livraison varient : jusqu'à 24 h côté Orange Money selon la charge. La même architecture couvre les deux.
Discutons de votre projet. Nous mettons en place l'idempotence, la vérification de signature et la réconciliation quotidienne sur votre boutique Wave et Orange Money, avec tests de rejeu inclus. 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.