Fiabiliser les webhooks de paiement Wave sur sa boutique (2026)

Le verdict en trois phrases

Sur une boutique qui encaisse via Wave ou Paystack, 3 à 5 % des commandes restent coincées « en attente » parce qu'un webhook s'est perdu ou a été traité deux fois. La solution robuste n'est pas le webhook seul : c'est webhook + polling de réconciliation, avec signature HMAC vérifiée, clé d'idempotence et endpoint qui répond en moins de 200 ms. Sans ce filet, vous laissez de l'argent encaissé sans commande validée — et des clients qui ont payé sans rien recevoir.

Les problèmes classiques et leurs correctifs

Un webhook est un simple appel HTTP du prestataire vers votre serveur. Tout ce qui peut casser un appel HTTP peut casser un webhook : timeout, redéploiement, double envoi, ordre inversé. Le symptôme est toujours le même côté client : une commande fantôme, payée mais jamais confirmée.

*Bonnes pratiques 2026 valables pour Wave, Paystack, Flutterwave et Orange Money.*

Webhook + polling : la ceinture et les bretelles

Le webhook est rapide mais faillible ; le polling est lent mais exhaustif. Combinés, ils garantissent qu'aucune commande payée ne reste orpheline. Le taux de webhooks manqués sans retry tourne autour de 2 % — assez pour ruiner la confiance si rien ne les rattrape.

La règle : l'endpoint webhook accuse réception immédiatement (200 OK sous 200 ms), puis pousse l'événement dans une file. Le traitement lourd — mise à jour stock, e-mail, facture — se fait ensuite, à l'abri des timeouts.

Mini cas pratique

Awa, gérante d'une boutique de cosmétiques à Dakar, encaisse 900 commandes/mois via Wave à 18 000 FCFA en moyenne. Avec un webhook seul, 4 % restent « en attente », soit 36 commandes bloquées pour 648 000 FCFA de chiffre d'affaires flou chaque mois — clients mécontents et remboursements manuels à la clé. Elle ajoute une clé d'idempotence et un polling toutes les 10 minutes. Le taux de commandes bloquées tombe sous 0,3 % : moins de 3 commandes/mois à traiter à la main. Coût : une demi-journée de développement, amortie dès la première semaine.

FAQ

Pourquoi certaines commandes restent-elles « en attente » ? Parce que le webhook de confirmation s'est perdu (timeout, redéploiement) ou n'a jamais été rejoué. Environ 2 % des webhooks se perdent sans mécanisme de retry, et sans polling ils ne sont jamais rattrapés.

Qu'est-ce qu'une clé d'idempotence ? C'est un identifiant unique par événement qui garantit qu'un même paiement n'est traité qu'une fois, même si le webhook arrive deux fois. Sans elle, vous risquez des commandes dupliquées et des décréments de stock erronés.

Faut-il un polling si j'ai déjà des webhooks ? Oui : le webhook seul plafonne autour de 98 % de fiabilité. Un polling de réconciliation toutes les 5-15 minutes rattrape les 2 % manquants et amène la fiabilité proche de 100 %.

Pourquoi répondre en moins de 200 ms ? Parce que si votre endpoint met trop de temps, le prestataire considère l'appel comme échoué et arrête de le renvoyer. Accusez réception immédiatement, puis traitez l'événement en asynchrone via une file.

Comment vérifier qu'un webhook est authentique ? Recalculez la signature HMAC avec votre clé secrète et comparez-la à celle envoyée dans l'en-tête. Si elles diffèrent, rejetez l'événement : c'est une tentative d'injection de faux paiement.

Discutons de votre projet. Nous fiabilisons vos webhooks Wave, Paystack et Orange Money avec idempotence, retry et polling de réconciliation. WhatsApp +221 77 596 93 33.