Le verdict en trois phrases
La cause numero un des "paiements perdus" n'est pas l'echec du paiement mais le webhook qui n'arrive jamais ou arrive en double. Sans cle d'idempotence, une livraison dupliquee (~1,5 %) cree une deuxieme commande ; sans retry, un echec de livraison (1 a 3 %) laisse la commande en attente. Un polling de reconciliation 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 : verification de signature, idempotence, retry programme et file de lettres mortes.
| Pilier | Mecanisme | Ordre de grandeur 2026 |
|---|---|---|
| Signature | HMAC-SHA256 | Rejet si invalide |
| Idempotence | Cle unique par event | Doublons ~1,5 % |
| Retry | Backoff exponentiel | 5s / 30s / 2m / 10m / 1h -> 24h |
| Dead-letter | File d'echecs persistants | Rejoue manuel |
| Polling secours | Query statut periodique | Rattrape ~4 % |
La verification HMAC-SHA256 garantit que l'appel vient bien du fournisseur, et non d'un attaquant qui simulerait un paiement reussi.
La machine a etats d'une transaction
Un paiement mobile money traverse des etats precis. Modeliser ces transitions evite les doubles confirmations et les remboursements fantomes.
| Etat | Signification | Transition possible |
|---|---|---|
| pending | Paiement declenche | -> processing, failed |
| processing | En attente de callback | -> success, failed |
| success | Confirme et journalise | -> reversed |
| failed | Echec ou timeout | -> pending (retry) |
| reversed | Rembourse / annule | etat final |
Chaque transition doit etre idempotente : recevoir deux fois le meme 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 gere une boutique en ligne a 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 bloquees en "processing" alors que le client avait paye, soit pres de 960 000 FCFA de flux en suspens et des dizaines de messages SAV. En ajoutant une cle d'idempotence et un polling toutes les 3 minutes, elle ramene les commandes bloquees a moins de 0,3 % et supprime la quasi-totalite des reclamations "j'ai paye mais rien recu".
FAQ
Pourquoi verifier la signature du webhook ? Sans verification HMAC-SHA256, n'importe qui connaissant votre URL pourrait simuler un paiement reussi. La signature prouve que l'appel vient reellement du fournisseur.
Qu'est-ce qu'une cle d'idempotence concretement ? C'est un identifiant unique de l'event que vous stockez avant traitement. Si le meme identifiant revient, vous ignorez le doublon au lieu de creer 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'a 24 h couvre la grande majorite des pannes temporaires cote reseau.
A quoi sert une dead-letter queue ? Elle conserve les events qui ont echoue apres tous les retries, pour rejeu manuel. Sans elle, ces paiements sont perdus definitivement.
Le polling suffit-il seul ? Il peut servir de filet unique, mais il est plus lent et plus couteux en appels API. Le bon design combine webhooks pour la vitesse et polling pour les ~4 % de cas manques.
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.
