Gérer les webhooks mobile money : idempotence et sécurité 2026

Le verdict en trois phrases

Un webhook de paiement mobile money n'est ni unique ni garanti : il peut arriver 1 à 3 fois selon le provider et parfois avec 10 secondes de retard. La fiabilité repose sur deux piliers : idempotence (dédup par référence) et vérification de signature (HMAC) pour rejeter les faux appels. Négliger l'un ou l'autre expose à 3 à 5 % de commandes dupliquées ou à des validations frauduleuses.

Idempotence : dédupliquer par référence

Le principe est simple : chaque transaction porte une reference unique. À la réception du webhook, vous vérifiez si cette référence a déjà été traitée. Si oui, vous renvoyez 200 immédiatement sans re-jouer la logique métier. Un stockage à TTL 24h (Redis ou table dédiée) suffit car les retries des providers s'étalent rarement au-delà d'une journée.

Les comportements de renvoi varient. MoMo (MTN) peut appeler votre callback 2 fois, Wave 1 à 3 fois selon les timeouts, Orange Money jusqu'à 3 fois. La latence moyenne d'arrivée du webhook après paiement se situe entre 4 et 12 secondes en 2026.

Sécurité et stratégies de retry

Côté sécurité, vérifiez toujours la signature sur le corps brut de la requête, ajoutez une allowlist d'IP quand le provider la publie, et rejetez tout appel non signé avec un 401. Côté fiabilité de VOS propres traitements aval (facture, e-mail, mise à jour stock), utilisez une file d'attente et un retry exponentiel pour absorber les pannes temporaires.

Mini cas pratique

Fatou, développeuse pour une épicerie en ligne à Dakar, encaissait 900 commandes/mois via Wave et Orange Money. Un pic de trafic provoquait des timeouts et des webhooks rejoués : environ 4,5 %, soit 40 commandes/mois, étaient dupliquées. Après ajout d'une clé d'idempotence à TTL 24h et d'une file avec retry exponentiel (2s, 8s, 32s), le taux de doublons est passé à 0,3 %. Le temps de support mensuel consacré aux litiges de double-paiement a chuté d'environ 12 heures, soit près de 90 000 FCFA de charge évitée.

FAQ

Pourquoi un webhook arrive-t-il plusieurs fois ? Parce que le provider considère l'appel échoué s'il ne reçoit pas un 200 rapide. Une réponse lente ou une erreur transitoire déclenche un renvoi : jusqu'à 3 fois pour Wave et Orange Money, 5 fois pour Paystack sur 24h.

Que stocker pour l'idempotence ? Au minimum la reference traitée et son statut, avec un TTL de 24h. Si la même référence revient, renvoyez 200 sans re-jouer la facture, l'e-mail ou la mise à jour stock.

Comment vérifier la signature correctement ? Calculez le HMAC sur le corps brut reçu, avant tout parsing JSON, puis comparez en temps constant. Un JSON re-sérialisé casse la signature et produit de faux 401.

Quel délai avant de considérer un paiement perdu ? Si aucun webhook n'arrive après 60 secondes, interrogez l'endpoint de vérification (GET status). La latence normale étant de 4 à 12 secondes, 60 secondes laisse une marge confortable.

Faut-il une file d'attente pour tout ? Non pour l'écriture « commande payée », qui doit être immédiate et idempotente. Oui pour les tâches aval (PDF, e-mail, sync compta) qui bénéficient d'un retry exponentiel et d'une dead-letter queue.

Discutons de votre projet. Nous fiabilisons vos encaissements mobile money avec webhooks idempotents, signatures vérifiées et files de retry. WhatsApp +221 77 596 93 33.