Le verdict en trois phrases
Le webhook est le seul signal fiable qu'un paiement Wave a réussi — jamais l'URL de retour du navigateur, qu'un client peut fermer avant qu'elle ne charge. En 2026, une intégration sérieuse repose sur trois piliers : vérification de signature, idempotence et réconciliation quotidienne. Sans idempotence, on observe 2 à 4 % de doublons dus aux retentes automatiques.
Se fier au webhook vs polling de statut
Les deux mécanismes sont complémentaires : le webhook est votre source principale, le polling votre filet de sécurité quand le webhook n'arrive pas (serveur down, réseau instable).
| Aspect | Webhook | Polling de statut |
|---|---|---|
| Latence | Quasi temps réel | 15 s à 3 min |
| Charge serveur | Faible | Plus élevée |
| Fiabilité si serveur down | Retenté par Wave | Dépend de votre cron |
| Rôle recommandé | Source principale | Secours / réconciliation |
| Risque de doublon | Oui (retentes) | Oui (si non dédupliqué) |
La bonne architecture : webhook en primaire, polling toutes les 15 secondes pendant 3 minutes en secours, puis un log de réconciliation quotidien qui rattrape les cas restants.
Retry, idempotence et réconciliation par provider (2026)
Ordres de grandeur 2026 selon la documentation des fournisseurs. Vérifiez toujours les valeurs exactes dans votre dashboard.
| Provider | Retentes webhook | Fenêtre de signature | Idempotency key | Réconciliation |
|---|---|---|---|---|
| Wave | 5x sur 24 h | 5 min | Obligatoire | Log quotidien |
| Paystack | 5x (backoff) | 5 min | event id | Dashboard + API |
| Flutterwave | 3x | verif-hash | tx_ref unique | API transactions |
| Orange Money | 3x / 30 s | signature HMAC | Recommandée | Export quotidien |
| CinetPay | 3x | token de vérif | cpm_trans_id | Dashboard |
La règle : chaque événement porte un identifiant unique ; votre base stocke les identifiants déjà traités et ignore les doublons avant tout crédit.
Les quatre règles d'un webhook robuste
- Vérifiez la signature dans la fenêtre de 5 minutes ; au-delà, rejetez (protection contre le rejeu).
- Soyez idempotent : une clé unique par transaction, un doublon = traitement ignoré. Cela élimine les 2-4 % de doublons dus aux retentes.
- Répondez vite : renvoyez HTTP 200 immédiatement, traitez en tâche de fond (file de retry). Un traitement lourd synchrone déclenche des retentes inutiles.
- Réconciliez chaque jour : comparez vos transactions locales à l'API du provider pour rattraper les webhooks perdus.
Mini cas pratique
Ibrahim, restaurateur à Abidjan, encaisse 1 200 commandes/mois via Wave, panier moyen 6 500 FCFA.
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.
- Sans idempotence, 3 % de doublons = 36 commandes traitées deux fois. Si 10 déclenchent un remboursement/geste commercial à 6 500 FCFA : 65 000 FCFA/mois perdus + temps SAV.
- Avec une clé d'idempotence : 0 doublon, et le log de réconciliation rattrape les ~1 % de webhooks manquants (12 commandes) qui seraient sinon « payées mais non validées ».
Coût d'implémentation de l'idempotence : quelques heures de dev, rentabilisé dès le premier mois.
FAQ
Puis-je me fier uniquement à l'URL de retour du navigateur ?
Non, jamais. Le client peut fermer l'onglet avant le chargement. Seul le webhook signé (complété par le polling) confirme un paiement de façon fiable.
Combien de fois Wave retente-t-il un webhook ?
L'ordre de grandeur est 5 fois sur 24 heures avec backoff. Votre endpoint doit donc être idempotent pour ne pas créditer plusieurs fois.
Qu'est-ce qu'une clé d'idempotence ?
Un identifiant unique par transaction. Si le même événement arrive deux fois, vous détectez la clé déjà traitée et ignorez le doublon — indispensable vu les 2-4 % de retentes.
Quelle est la fenêtre de vérification de signature ?
Environ 5 minutes chez Wave et Paystack. Au-delà, rejetez la requête pour éviter les attaques par rejeu.
À quoi sert la réconciliation quotidienne ?
À rattraper les webhooks jamais reçus (serveur momentanément indisponible). Un cron compare vos transactions à l'API du provider et corrige les écarts.
Discutons de votre projet. Nous bâtissons des webhooks Wave, Paystack et Flutterwave robustes, idempotents et réconciliés. 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.