Le verdict en trois phrases
Un webhook de paiement est rejoué plusieurs fois par conception : Wave et les opérateurs renvoient la même notification jusqu'à cinq fois pour garantir la livraison. Sans clé d'idempotence, chaque rejeu recrée une commande, générant 2 à 4 % de doublons qui polluent stock et comptabilité. La parade tient en trois piliers : signature HMAC vérifiée, clé d'idempotence stockée, fenêtre de déduplication de 24 heures.
Les 6 événements critiques à gérer
Un webhook ne dit pas seulement « payé ». Il transporte une série d'événements dont chacun déclenche une action différente dans votre système.
| Événement | Signification | Action commande | Réversible |
|---|---|---|---|
| payment.success | Paiement confirmé | Valider et préparer | Oui |
| payment.failed | Paiement échoué | Libérer le stock | Non |
| payment.pending | En attente de confirmation | Réserver le stock | Oui |
| payment.reversed | Paiement annulé | Rembourser et restocker | Non |
| payment.chargeback | Litige client | Geler et enquêter | Non |
| payment.refund | Remboursement émis | Créditer et restocker | Non |
Ignorer l'un de ces événements crée des incohérences : une commande payée non validée, ou un stock bloqué sur un paiement échoué.
La table des statuts et actions idempotentes
L'idempotence signifie qu'un même événement traité deux fois produit exactement le même résultat. Voici comment chaque statut se comporte face à un rejeu.
| Statut reçu | 1er traitement | Rejeu identique | Garde-fou |
|---|---|---|---|
| success (nouveau) | Créer la commande | Ignorer (déjà traité) | Clé d'idempotence |
| success (déjà vu) | — | Ignorer | Fenêtre 24 h |
| failed | Marquer échec | Ignorer | Statut final |
| reversed après success | Rembourser | Ignorer 2e reversed | Log unique |
| signature invalide | Rejeter (401) | Rejeter | HMAC |
| événement hors ordre | Mettre en file | Réordonner | Horodatage |
L'impact d'un webhook non idempotent
Voici ce que coûte l'absence d'idempotence sur une boutique traitant 3 000 paiements/mois, panier moyen 14 000 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.
| Indicateur | Sans idempotence | Avec idempotence | Écart |
|---|---|---|---|
| Taux de doublons | 3 % | 0,1 % | -2,9 pts |
| Commandes dupliquées/mois | 90 | 3 | -87 |
| Remboursements à traiter | 90 | 3 | -87 |
| Temps SAV mensuel | 9 h | 0,5 h | -8,5 h |
| Stock bloqué à tort | fréquent | rare | — |
À 14 000 FCFA de panier, 87 doublons représentent 1 218 000 FCFA de transactions à annuler et rembourser chaque mois, sans compter le coût SAV.
Mini cas pratique
Fatou vend des vêtements en ligne à Dakar via Wave, 3 000 commandes/mois. Son webhook créait une commande à chaque rejeu : elle traitait 90 doublons par mois, soit 9 heures de SAV et des clients agacés d'être débités deux fois. En ajoutant une clé d'idempotence (référence de transaction Wave) et une déduplication sur 24 h, ses doublons tombent à 3 par mois. Elle récupère 8,5 heures et supprime la quasi-totalité des litiges de double débit.
FAQ
Qu'est-ce qu'une clé d'idempotence concrètement ? C'est un identifiant unique par transaction (souvent la référence Wave) que vous stockez au premier traitement. Si le même identifiant revient, vous ignorez le rejeu au lieu de recréer la commande.
Pourquoi vérifier la signature HMAC ? Elle prouve que le webhook vient bien de Wave et non d'un fraudeur qui simule un paiement. Sans vérification, n'importe qui pourrait valider une commande gratuitement.
Combien de temps garder la fenêtre de déduplication ? 24 heures couvrent la quasi-totalité des rejeux opérateur, qui s'étalent sur quelques minutes à quelques heures. Au-delà, le risque de rejeu tardif devient négligeable.
Que faire d'un événement reçu dans le désordre ? Un paiement peut arriver avant sa création de commande. On met l'événement en file et on le réordonne par horodatage pour éviter un état incohérent.
Les webhooks échoués sont-ils rejoués ? Oui, si votre serveur renvoie une erreur, Wave retente jusqu'à cinq fois avec un délai croissant. Votre endpoint doit répondre 200 rapidement, quitte à traiter en asynchrone.
Discutons de votre projet. Nous fiabilisons vos webhooks Wave avec signature HMAC et idempotence pour supprimer les doubles commandes. 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.