Webhook Wave : fiabiliser la confirmation de paiement en 2026

Le verdict en trois phrases

Une commande fantôme — payée mais jamais confirmée, ou confirmée deux fois — vient presque toujours d'un webhook mal traité. La bonne architecture 2026 repose sur trois piliers : vérification de la signature HMAC, clé d'idempotence obligatoire, et réponse HTTP 200 en moins de 10 secondes. Le polling ne doit servir que de filet de sécurité, jamais de mécanisme principal.

Polling vs webhook signé

Le polling interroge l'API Wave à intervalles réguliers pour connaître le statut d'un paiement. Simple à écrire, mais lent, coûteux en appels et fragile en cas de forte charge. Le webhook signé, lui, est poussé par Wave dès que l'état change : plus rapide, plus fiable, mais il exige une vraie discipline de sécurité et de déduplication.

En pratique, on combine les deux : webhook pour la réactivité, polling de réconciliation une fois par heure pour rattraper les événements manqués.

Les règles de fiabilité incontournables

Wave réémet un webhook tant qu'il n'a pas reçu un 200. Sans idempotence, un même paiement peut donc déclencher plusieurs fois la logique métier — double envoi, double décrément de stock. La clé d'idempotence (souvent l'event_id) stockée en base bloque ces rejeux.

Règle d'or : répondez 200 immédiatement après avoir enregistré l'événement, puis traitez la logique lourde en tâche de fond. Un traitement synchrone trop long provoque un timeout, donc un retry, donc un doublon.

Mini cas pratique

Ibrahim, restaurateur à Dakar, encaisse 400 commandes Wave par mois. Avec un taux de doublons de 3 %, ce sont 12 événements dupliqués mensuels. Sans idempotence, 12 clients risquaient un double débit logique ou une double préparation. En stockant l'event_id et en rejetant les rejeux, il passe à 0 commande fantôme et économise le temps de support qu'il chiffrait à 2 heures par semaine.

FAQ

Pourquoi reçois-je le même webhook plusieurs fois ?

Parce que Wave réémet l'événement tant qu'il n'obtient pas un HTTP 200, et parfois par redondance réseau. En 2026, comptez 2 à 4 % de doublons : une clé d'idempotence sur l'event_id les neutralise.

Combien de temps Wave réessaie-t-il ?

Les retries s'étalent jusqu'à 24 heures avec un intervalle croissant. Votre endpoint doit donc rester idempotent sur toute cette fenêtre, pas seulement quelques minutes.

Dois-je vérifier la signature du webhook ?

Oui, systématiquement. La vérification HMAC garantit que la requête vient bien de Wave et pas d'un attaquant qui simule un paiement réussi. Un webhook non signé ou mal signé doit être rejeté.

Quel timeout configurer ?

Répondez en moins de 10 secondes. Enregistrez l'événement, renvoyez 200, puis traitez en asynchrone : un traitement synchrone lent déclenche un timeout et donc un doublon.

Combien de temps garder les logs ?

Au moins 90 jours. Cela couvre les litiges, les réconciliations et l'audit des paiements sans surcharger votre stockage.

Discutons de votre projet. On sécurise vos webhooks Wave — signature, idempotence, réconciliation — pour zéro commande fantôme. WhatsApp +221 77 596 93 33.