Le verdict en trois phrases
En paiement mobile money, le webhook est la vérité de votre commande — et il est faillible. Sans clé d'idempotence, un événement rejoué crée une double commande ; sans vérification de signature, vous acceptez de faux paiements ; sans fallback de polling, un webhook perdu vous fait rater une vente pourtant payée. La fiabilité tient en trois piliers : idempotence, signature, réconciliation.
Handler naïf ou traitement idempotent : quelle différence ?
Un handler naïf traite l'événement inline, fait confiance au payload et n'a pas de rejeu. Un traitement robuste vérifie, met en file et rend l'opération rejouable sans effet de bord.
| Critère | Handler naïf | Traitement idempotent |
|---|---|---|
| Vérification signature | absente | obligatoire |
| Doublons | ~1,2 % de commandes | ~0 % |
| Retries opérateur | ignorés | 5 tentatives, backoff exponentiel |
| Événements perdus | vente ratée | rattrapés par polling 60 s |
| Budget de traitement | non borné | 5 s max, sinon 200 + async |
| Échecs persistants | perdus | dead-letter queue |
La règle d'or : répondre 200 immédiatement, mettre l'événement en file, puis traiter en asynchrone de façon idempotente. Un opérateur qui n'a pas son 200 sous quelques secondes rejoue — d'où les doublons.
Quels chiffres viser en 2026 ?
Ces ordres de grandeur guident le dimensionnement d'un pipeline de webhooks fiable pour Wave, Paystack et M-Pesa.
| Métrique | Cible / valeur 2026 |
|---|---|
| Taux de retries webhook | 3 à 8 % des événements |
| Doublons sans clé d'idempotence | ~1,2 % |
| Tentatives avec backoff | 5 (ex. 1s, 2s, 4s, 8s, 16s) |
| Fréquence du polling fallback | toutes les 60 s |
| Budget de traitement par événement | 5 s |
| Confirmation de commande | uniquement sur événement vérifié |
| Dead-letter queue | après 5 échecs |
La commande n'est confirmée que sur un événement vérifié (signature valide + statut succès), jamais sur le simple retour du navigateur client, facilement falsifiable.
Mini cas pratique
Moussa, développeur d'une boutique à Nairobi, subissait 1,2 % de doubles commandes : sur 5 000 paiements/mois, cela faisait 60 commandes fantômes à traiter manuellement, environ 5 h de SAV. Il ajoute une clé d'idempotence basée sur l'ID de transaction opérateur et une file d'attente avec dead-letter queue. Les doublons tombent à zéro. Le polling toutes les 60 s rattrape en plus les 4 % de webhooks perdus, soit environ 200 ventes/mois auparavant confirmées en retard, désormais bouclées automatiquement.
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.
FAQ
Qu'est-ce qu'une clé d'idempotence concrètement ?
Un identifiant unique (souvent l'ID de transaction opérateur) que vous stockez avant de traiter. Si le même arrive deux fois, vous ignorez le second : zéro double commande, même sur rejeu.
Pourquoi vérifier la signature du webhook ?
Parce que sans elle, n'importe qui peut poster un faux événement « paiement réussi » et déclencher une livraison non payée. La vérification de signature est non négociable en 2026.
Le polling remplace-t-il les webhooks ?
Non, il les complète. Le webhook donne l'instantané ; le polling toutes les 60 s rattrape les 3 à 8 % d'événements perdus ou retardés. Les deux ensemble donnent la fiabilité.
Que faire d'un événement qui échoue 5 fois ?
On l'envoie en dead-letter queue pour inspection manuelle, plutôt que de le rejouer à l'infini. Cela isole les cas pathologiques sans bloquer le flux normal.
Devenez apporteur d'affaires Kolonell. Vous connaissez un e-commerçant qui perd des paiements faute de webhooks fiables ? Recommandez-le : la commission apporteur est de 12 % sur un e-commerce, 15 % + 5 % récurrent sur une vitrine, 10 % sur une marketplace et 8 % sur l'institutionnel.
Discutons de votre projet. On construit un pipeline de webhooks idempotent, signé et réconcilié, testé avec des paiements réels. 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.
