Le verdict en trois phrases
Le callback front-end — la page "paiement réussi" affichée au navigateur — est trivial à falsifier et ne prouve rien : seul le webhook signé de l'opérateur fait foi. Une intégration fiable vérifie la signature HMAC en moins de 5 secondes, stocke le payload brut, déduplique par transaction id et rejoue les livraisons échouées avec un backoff exponentiel 1/5/25 s. Sans ces quatre garde-fous, vous livrez des commandes non payées et vous en livrez d'autres deux fois.
Les 4 garde-fous non négociables
Un webhook mobile money n'est fiable que s'il résiste à la falsification, aux doublons, au rejeu et aux pannes réseau. Voici la checklist et les cibles 2026.
| Garde-fou | Rôle | Cible 2026 |
|---|---|---|
| Signature HMAC | Prouver que l'opérateur est l'émetteur | Vérifier < 5 s, rejeter sinon 401 |
| Idempotence | Empêcher le double traitement | Dédupe par transaction id unique |
| Anti-rejeu | Bloquer un payload rejoué | Timestamp + fenêtre 5 min |
| Payload brut stocké | Preuve et re-traitement | Conserver 100 % avant parsing |
Règle d'or : traitez le webhook comme une commande à valider, pas comme une confirmation à afficher. Le front-end déclenche l'UX ; le webhook débloque la livraison.
File de retry et dead-letter
Les opérateurs réémettent les webhooks quand votre serveur répond en erreur ou trop lentement. Sans file de retry côté opérateur ET côté vous, une panne de 30 secondes peut perdre une vente. Voici les paramètres à configurer.
| Paramètre | Ordre de grandeur 2026 | Pourquoi |
|---|---|---|
| Timeout réponse serveur | Répondre < 3 s (200 OK) | Éviter le retry inutile |
| Backoff exponentiel | 1 s, 5 s, 25 s, 125 s | Laisser le serveur récupérer |
| Tentatives avant dead-letter | 5 à 6 | Au-delà, alerte humaine |
| Alerte échec livraison | Après > 3 échecs consécutifs | Prévenir avant la perte |
| Rétention payload | 90 jours minimum | Reconciliation et litiges |
| Taux de webhooks perdus | Cible < 0,1 % | Mesuré, pas supposé |
Astuce d'architecture : répondez 200 OK immédiatement après avoir stocké le payload brut, puis traitez en asynchrone via une file. Un webhook qui attend la fin du traitement métier finit toujours en timeout un jour de pic.
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, restaurateur à Abidjan, reçoit 90 commandes par jour via Wave et MTN. Un vendredi soir, son serveur sature et met 12 s à répondre : l'opérateur rejoue 4 webhooks, ce qui déclenche 4 doubles préparations en cuisine (perte ≈ 18 000 FCFA). Après refonte : réponse 200 OK en 0,8 s, dédupe par transaction id, traitement asynchrone. Le pic suivant, 130 commandes, aucun doublon, aucune commande perdue. Le seul incident — un webhook au timestamp expiré — est correctement rejeté et loggé.
FAQ
Pourquoi ne pas faire confiance à la page de succès affichée au client ? Parce qu'elle vit dans le navigateur et peut être rejouée ou falsifiée en quelques secondes. Seul le webhook signé HMAC de l'opérateur prouve qu'un paiement a réellement eu lieu.
Qu'est-ce que l'idempotence concrètement ? C'est garantir qu'un même webhook reçu deux fois ne déclenche qu'une seule livraison. On y arrive en dédupliquant sur le transaction id unique de l'opérateur avant tout traitement.
Comment gérer un pic de trafic sans perdre de paiement ? Répondez 200 OK en moins de 3 s après avoir stocké le payload brut, puis traitez en file asynchrone. Le backoff 1/5/25 s de l'opérateur couvre les micro-pannes.
Combien de temps garder les payloads ? Au minimum 90 jours, pour la reconciliation et les litiges. Le payload brut est votre preuve en cas de contestation d'un client ou d'un opérateur.
Quand faut-il alerter un humain ? Dès plus de 3 échecs de livraison consécutifs sur un même webhook, ou lorsqu'un message atteint la dead-letter queue après 5-6 tentatives. Au-delà, chaque minute peut coûter une vente.
Discutons de votre projet. Nous construisons des webhooks mobile money signés, idempotents et à toute épreuve, avec file de retry et alertes. 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.
