Le verdict en trois phrases
Un webhook de paiement rejoué crée une double commande, un webhook perdu crée une vente fantôme : les deux détruisent la confiance et faussent votre comptabilité. La parade tient en trois piliers — clé d'idempotence obligatoire, vérification de signature HMAC et file de retries avec reconciliation. En 2026, un checkout mobile money sérieux doit absorber 2 à 5 % de webhooks dupliqués et 0,3 % de perdus sans jamais créditer deux fois ni oublier une vente.
Les incidents webhook et leur parade
Chaque agrégateur renvoie des notifications asynchrones. Sans discipline, elles produisent des erreurs silencieuses. Voici les cas typiques 2026 et la bonne réponse technique.
| Incident | Fréquence observée | Conséquence | Parade |
|---|---|---|---|
| Webhook dupliqué | 2-5 % | Double crédit / double commande | Clé d'idempotence unique |
| Webhook perdu | 0,3 % | Vente non enregistrée | Polling + reconciliation |
| Ordre inversé (pending après paid) | 1-2 % | Statut incohérent | Horodatage + machine à états |
| Signature invalide | rare | Fraude possible | Vérification HMAC stricte |
| Timeout endpoint | variable | Retries en cascade | Réponse < 5 s, traitement async |
Une clé d'idempotence (souvent l'ID de transaction du provider) stockée en base avec contrainte d'unicité neutralise à elle seule la majorité des doublons.
Retries, signatures et délais
Les agrégateurs rejouent les webhooks jusqu'à réception d'un accusé 2xx. Vos paramètres doivent s'aligner sur leur politique.
| Paramètre | Bonne pratique 2026 | Raison |
|---|---|---|
| Réponse HTTP attendue | 200 en < 5 s | Éviter les retries inutiles |
| Politique de retry | exponentielle jusqu'à 24 h | Absorber les pannes réseau |
| Fenêtre signature HMAC | 5 min de tolérance | Bloquer les rejeux tardifs |
| Stockage idempotence | 30-90 jours | Couvrir les rejeux tardifs |
| Reconciliation | quotidienne | Rattraper les 0,3 % perdus |
| Traitement métier | asynchrone (file) | Répondre vite, traiter ensuite |
Le principe d'or : accuser réception vite, traiter lentement. On répond 200 immédiatement, on empile en file, puis on exécute la logique métier idempotente.
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.
Mini cas pratique
Fatou, développeuse d'une boutique à Thiès, encaisse 800 commandes par mois. À 3 % de webhooks dupliqués, cela fait 24 notifications en double par mois. Avant idempotence, 24 clients risquaient un double débit ou une double expédition ; à un panier moyen de 15 000 FCFA, l'exposition mensuelle atteint 360 000 FCFA de litiges potentiels. Une simple contrainte d'unicité sur l'ID de transaction ramène ce risque à zéro, pour deux heures de développement.
FAQ
Qu'est-ce qu'une clé d'idempotence concrètement ? C'est un identifiant unique par transaction (souvent fourni par l'agrégateur) que vous stockez ; si le même arrive deux fois, vous ignorez le doublon. Elle bloque 2 à 5 % de webhooks rejoués.
Pourquoi vérifier la signature HMAC ? Pour garantir que le webhook vient bien de l'agrégateur et n'a pas été falsifié. Sans elle, un attaquant pourrait simuler un paiement réussi.
Combien de temps garder les webhooks reçus ? 30 à 90 jours suffisent pour couvrir les rejeux tardifs et servir de piste d'audit lors des reconciliations.
Que faire des 0,3 % de webhooks perdus ? Les rattraper par un polling quotidien de l'API de statut et une reconciliation qui compare vos commandes aux transactions confirmées côté provider.
Un timeout d'endpoint est-il grave ? Oui : s'il dépasse 5 secondes, l'agrégateur relance, ce qui multiplie les doublons. D'où le traitement asynchrone après un 200 immédiat.
Discutons de votre projet. Nous bâtissons des webhooks idempotents, signés et reconciliés pour un encaissement sans double crédit ni vente fantôme. 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.
