Le verdict en trois phrases
La cause numéro un des "paiements perdus" n'est pas l'échec du paiement mais le webhook qui n'arrive jamais ou arrive en double. Sans clé d'idempotence, une livraison dupliquée (~1,5 %) crée une deuxième commande ; sans retry, un échec de livraison (1 à 3 %) laisse la commande en attente. Un polling de réconciliation en secours rattrape les ~4 % de commandes qui resteraient sinon dans les limbes.
L'anatomie d'un webhook fiable
Un webhook robuste repose sur quatre piliers : vérification de signature, idempotence, retry programmé et file de lettres mortes.
| Pilier | Mécanisme | Ordre de grandeur 2026 |
|---|---|---|
| Signature | HMAC-SHA256 | Rejet si invalide |
| Idempotence | Clé unique par event | Doublons ~1,5 % |
| Retry | Backoff exponentiel | 5s / 30s / 2m / 10m / 1h -> 24h |
| Dead-letter | File d'échecs persistants | Rejoue manuel |
| Polling secours | Query statut périodique | Rattrape ~4 % |
La vérification HMAC-SHA256 garantit que l'appel vient bien du fournisseur, et non d'un attaquant qui simulerait un paiement réussi.
La machine à états d'une transaction
Un paiement mobile money traverse des états précis. Modéliser ces transitions évite les doubles confirmations et les remboursements fantômes.
| État | Signification | Transition possible |
|---|---|---|
| pending | Paiement déclenché | -> processing, failed |
| processing | En attente de callback | -> success, failed |
| success | Confirmé et journalisé | -> reversed |
| failed | Échec ou timeout | -> pending (retry) |
| reversed | Rembourse / annulé | état final |
Chaque transition doit être idempotente : recevoir deux fois le même event success ne doit jamais confirmer la commande deux fois.
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
Awa gère une boutique en ligne à Dakar avec 1 200 commandes par mois, panier moyen 20 000 FCFA. Avant, sans polling de secours, environ 4 % des commandes (48 par mois) restaient bloquées en "processing" alors que le client avait payé, soit près de 960 000 FCFA de flux en suspens et des dizaines de messages SAV. En ajoutant une clé d'idempotence et un polling toutes les 3 minutes, elle ramène les commandes bloquées à moins de 0,3 % et supprime la quasi-totalité des réclamations "j'ai payé mais rien reçu".
FAQ
Pourquoi vérifier la signature du webhook ? Sans vérification HMAC-SHA256, n'importe qui connaissant votre URL pourrait simuler un paiement réussi. La signature prouve que l'appel vient réellement du fournisseur.
Qu'est-ce qu'une clé d'idempotence concrètement ? C'est un identifiant unique de l'event que vous stockez avant traitement. Si le même identifiant revient, vous ignorez le doublon au lieu de créer une seconde commande.
Quel calendrier de retry adopter ? Un backoff exponentiel type 5 s, 30 s, 2 min, 10 min, 1 h puis toutes les heures jusqu'à 24 h couvre la grande majorité des pannes temporaires côté réseau.
À quoi sert une dead-letter queue ? Elle conserve les events qui ont échoué après tous les retries, pour rejeu manuel. Sans elle, ces paiements sont perdus définitivement.
Le polling suffit-il seul ? Il peut servir de filet unique, mais il est plus lent et plus coûteux en appels API. Le bon design combine webhooks pour la vitesse et polling pour les ~4 % de cas manqués.
Discutons de votre projet. Nous construisons votre couche de webhooks avec idempotence, retry et polling de secours pour ne plus jamais perdre un paiement. 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.
