Le verdict en trois phrases
Un webhook perdu signifie une commande payée par le client mais jamais confirmée dans votre système : le pire scénario e-commerce. La solution n'est pas d'espérer que Wave livre parfaitement, mais de combiner signature HMAC, retries programmes et réconciliation active via l'API getStatus. Avec ce triptyque, on passe d'un taux de perte de 2-4 % à une couverture proche de 100 %.
Pourquoi un webhook seul ne suffit jamais
Un webhook est une requête HTTP que Wave envoie à votre serveur quand un paiement change d'état. Le problème : cette requête peut échouer pour mille raisons (serveur momentanément indisponible, timeout réseau, déploiement en cours, pic de charge). Sans stratégie de secours, chaque échec est un paiement orphelin.
Voici les ordres de grandeur observés en 2026 sur des intégrations mobile money ouest-africaines :
| Métrique | Valeur (estimation 2026) | Conséquence |
|---|---|---|
| Webhooks perdus sans retry | 2 à 4 % | Commandes payées non confirmées |
| Délai moyen de livraison webhook | 3 à 8 s | Ne pas afficher "échec" trop tôt |
| Fenêtre de réconciliation recommandée | T+1 (24 h) | Rattrapage quotidien des écarts |
| Faux statut "pending" persistant | 1,5 % | Vérification API obligatoire |
| Retries opérateur avant abandon | 3 à 5 | Idempotence indispensable |
La leçon : le webhook est le canal rapide, mais il doit toujours avoir une doublure.
La signature HMAC : refuser tout ce qui n'est pas Wave
Avant de traiter un webhook, vérifiez sa signature. Wave signe chaque payload avec un secret partagé (HMAC-SHA256). Vous recalculez la signature de votre côté et comparez : si ça ne correspond pas, vous rejetez la requête avec un code 401. Cela bloque les tentatives de faux paiements injectés par un attaquant qui devinerait votre URL.
Règle d'or : ne jamais faire confiance au montant présent dans le webhook seul. Recroisez toujours avec la commande côté base de données (montant, référence marchande, devise) avant de marquer la commande comme payée.
Retries et fallback polling : la ceinture et les bretelles
Deux mécanismes complémentaires sécurisent l'encaissement :
| Mécanisme | Déclenchement | Rythme | Rôle |
|---|---|---|---|
| Retry webhook interne | Échec de traitement | 5 min, 15 min, 60 min | Rejouer un webhook échoue |
| Polling API getStatus | Commande "pending" > 10 min | Toutes les 10 min, 6 fois max | Rattraper un webhook jamais reçu |
| Réconciliation quotidienne | Batch nocturne | 1 fois/jour à T+1 | Croiser relevé Wave et commandes |
| Alerte manuelle | Écart non résolu | Immédiate | Intervention humaine |
Concrètement : si un webhook n'est jamais arrivé au bout de 10 minutes, votre serveur interroge lui-même l'API Wave pour connaître l'état réel de la transaction. C'est le filet de sécurité qui rattrape les 2-4 % de webhooks perdus.
Mini cas pratique
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.
Awa gère une boutique de cosmétiques à Dakar qui traite 900 commandes par mois à un panier moyen de 18 000 FCFA, soit 16 200 000 FCFA de chiffre d'affaires mensuel. Sans retry ni polling, elle perd en moyenne 3 % de confirmations, soit 27 commandes non confirmées automatiquement chaque mois.
Ces 27 commandes représentent 486 000 FCFA qui restent bloquées en "pending" : clients relancés par erreur, temps du service client, parfois remboursements à tort. En activant le polling getStatus toutes les 10 minutes et la réconciliation T+1, Awa ramène les commandes non confirmées à moins de 1 par mois. Gain net : environ 470 000 FCFA de CA sécurise chaque mois et 6 heures de service client économisées.
FAQ
Combien de webhooks se perdent vraiment sans retry ?
Entre 2 % et 4 % selon nos observations 2026 sur mobile money ouest-africain. Sur 1 000 commandes, cela représente 20 à 40 paiements orphelins par mois, largement suffisant pour justifier un fallback.
À quelle fréquence dois-je faire le polling API ?
Toutes les 10 minutes, avec un maximum de 6 tentatives (soit une fenêtre de 1 heure). Au-delà, la transaction bascule en réconciliation quotidienne T+1 plutôt que d'épuiser inutilement l'API.
La signature HMAC ralentit-elle le traitement ?
Non. Le calcul HMAC-SHA256 prend moins de 1 ms. C'est négligeable face aux 3 à 8 secondes de latence réseau du webhook lui-même, et le gain en sécurité est énorme.
Que faire d'un statut "pending" qui ne change jamais ?
Environ 1,5 % des transactions restent en faux "pending". La règle : au-delà de 60 minutes, considérer le paiement comme échoué après une dernière vérification getStatus, et libérer le stock réservé.
La réconciliation quotidienne est-elle vraiment nécessaire si j'ai déjà le polling ?
Oui. Le polling rattrape l'immédiat, la réconciliation T+1 attrape les cas résiduels (frais, remboursements, écarts de montant) et vous donne une piste d'audit comptable propre.
Discutons de votre projet. Nous intégrons Wave avec signature HMAC, retries et réconciliation activé pour que vous ne perdiez plus jamais 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.
