Le verdict en trois phrases
Un webhook est l'appel serveur-à-serveur qui confirme un paiement : s'il n'est pas vérifié, un attaquant peut envoyer un faux callback et déclencher une livraison gratuite. Deux garde-fous sont non négociables : la vérification de signature HMAC et l'idempotence, qui évite les doubles crédits (jusqu'à 1 à 2 % des cas). Répondez en moins de 5 secondes et conservez les logs 90 jours et plus.
Les quatre contrôles indispensables
Un webhook robuste empile quatre defenses. Chacune bloque une attaque ou une erreur précise.
| Contrôle | Attaque bloquée | Coût d'implémentation | Priorité |
|---|---|---|---|
| Signature HMAC | Faux callback | Faible | Critique |
| Idempotence (ID unique) | Double crédit | Faible | Critique |
| Liste blanche IP | Requêtes hors PSP | Moyen | Élevée |
| Anti-rejeu (timestamp) | Rejeu d'un vrai callback | Faible | Élevée |
| Vérification relevé | Paiement fantôme | Moyen | Élevée |
La signature HMAC compare un hash calcule avec le secret partagé : si le hash ne correspond pas, la requête est rejetée avant tout traitement.
Règles de réponse et de journalisation
Le comportement de réponse conditionne la fiabilité. Un webhook mal répondu déclenche des retries et des doublons.
| Règle | Valeur cible 2026 | Pourquoi |
|---|---|---|
| Délai de réponse | < 5 s | Évite les retries du PSP |
| Code succès | 200 systématique | Stoppe la file de retry |
| Traitement asynchrone | File d'attente | Répondre vite, traiter après |
| Tolérance timestamp | 5 min | Bloque le rejeu tardif |
| Rétention des logs | 90+ jours | Preuve et debug litiges |
| Déduplication | Par ID transaction | 1-2 % de doubles évités |
Bonne pratique : accusez réception (200) immédiatement, puis traitez la commande dans une file asynchrone. Ne bloquez jamais la réponse le temps d'un long traitement.
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 pour une boutique à Thiès, reçoit un signalement : deux clients ont été livrés sans avoir payé. Enquête : son endpoint acceptait tout POST sans vérifier la signature. Un plaisantin avait rejoue un vrai callback. Correctif en une journée : vérification HMAC (rejet des signatures invalides), idempotence par ID de transaction (les 2 doublons du mois disparaissent), et tolérance de timestamp à 5 minutes contre le rejeu. Sur 1 800 webhooks/mois, elle bloque désormais une dizaine de requêtes suspectes et zéro double crédit. Coût : une journée de dev, contre des centaines de milliers de FCFA de marchandise offerte évitée.
FAQ
Qu'est-ce qu'une signature HMAC ? C'est un hash calculé à partir du corps du message et d'un secret partagé avec le PSP. Vous recalculez ce hash à réception : s'il différé, le callback est faux et doit être rejeté avant tout traitement.
Pourquoi l'idempotence est-elle critique ? Parce que les PSP renvoient parfois le même callback (retry). Sans déduplication par ID de transaction, vous créditez deux fois la commande dans 1 à 2 % des cas, faussant stock et comptabilité.
Faut-il une liste blanche d'IP ? C'est un bon complément, mais pas suffisant seul car les IP des PSP changent. Combinez-la avec la signature HMAC, qui reste la défense principale.
Combien de temps garder les logs ? Au moins 90 jours. Ils servent de preuve en cas de litige, permettent de rejouer un traitement et facilitent la réconciliation des paiements manquants.
Que faire si mon webhook est lent ? Répondez 200 en moins de 5 secondes puis traitez en file asynchrone. Un endpoint lent déclenche des retries du PSP et multiplie les risques de doublons.
Discutons de votre projet. Nous sécurisons vos endpoints de paiement avec signature, idempotence et logs tracés. 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.
