Le verdict en trois phrases
Un webhook de paiement mal fiabilisé, c'est 2 à 5 % de notifications perdues — donc des commandes payées jamais validées et des clients furieux. Trois protections sont non négociables : la signature HMAC pour authentifier l'appel, la clé d'idempotence pour empêcher le double-crédit, et une file de retry exponentielle. En complément, un polling de secours toutes les 15 minutes récupère les rares webhooks définitivement perdus.
Les trois piliers d'un webhook fiable
Chaque pilier répond à un risque précis et mesurable.
| Pilier | Risque couvert | Sans la protection |
|---|---|---|
| Signature HMAC | Faux webhook / fraude | Crédit sur appel falsifié |
| Idempotence | Double livraison du webhook | Double-crédit de la commande |
| Retry exponentiel | Indisponibilité passagère | 2-5 % de webhooks perdus |
| Polling de secours | Webhook définitivement perdu | Commande payée non validée |
On ne choisit pas entre ces mécanismes : les quatre se cumulent. La signature protège l'entrée, l'idempotence protège le traitement, le retry et le polling protègent la livraison.
La file de retry exponentielle
Quand votre endpoint renvoie une erreur ou timeout, l'opérateur — ou votre propre file — retente selon un intervalle croissant.
| Tentative | Délai après échec | Cumul écoulé |
|---|---|---|
| 1 | Immédiat | 0 |
| 2 | +1 min | 1 min |
| 3 | +15 min | 16 min |
| 4 | +2 h | ~2 h 16 |
| 5 | +12 h | ~14 h |
Cinq tentatives réparties sur ~24 h rattrapent la quasi-totalité des indisponibilités passagères. Au-delà, c'est le polling de réconciliation qui prend le relais.
Mini cas pratique
Moussa, développeur pour une boutique en ligne à Dakar, observait ~3 % de commandes bloquées en statut « en attente » alors qu'elles étaient payées — soit ~9 commandes/jour sur 300. Chaque commande bloquée générait un ticket support de ~8 minutes, soit 72 min/jour perdues. Après avoir ajouté idempotence + retry sur 24 h + polling toutes les 15 min, le taux de commandes bloquées est tombé à ~0,2 %, soit moins d'1 commande/jour. Économie : ~70 min de support/jour et zéro double-crédit.
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
Combien de webhooks se perdent sans retry ?
Entre 2 et 5 % selon la stabilité de votre endpoint et de l'opérateur. Un retry exponentiel sur 24 h ramène ce chiffre sous 0,3 %.
Pourquoi une clé d'idempotence est-elle indispensable ?
Parce qu'un opérateur peut livrer le même webhook deux fois. Sans clé d'idempotence, vous créditez la commande deux fois. La clé garantit qu'un identifiant de transaction n'est traité qu'une seule fois.
Comment vérifier la signature HMAC ?
Vous recalculez le HMAC du corps de la requête avec votre clé secrète et comparez à l'en-tête envoyé. Si les deux diffèrent, l'appel est rejeté : c'est votre barrière anti-fraude.
Le polling remplace-t-il les webhooks ?
Non, c'est un filet de sécurité. Les webhooks restent la voie principale (instantanée) ; le polling toutes les 15 min ne rattrape que les cas résiduels perdus après les 5 tentatives de retry.
Quel délai de traitement viser pour un webhook ?
Moins de 2 à 3 secondes de traitement synchrone, sinon l'opérateur considère l'appel en échec. On accuse réception vite, puis on traite en asynchrone.
Discutons de votre projet. On fiabilise vos webhooks Wave/OM/Paystack avec idempotence, retry et polling de secours. 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.
