Le verdict en trois phrases
Un webhook est l'appel serveur-a-serveur qui confirme un paiement : s'il n'est pas verifie, un attaquant peut envoyer un faux callback et declencher une livraison gratuite. Deux garde-fous sont non negociables : la verification de signature HMAC et l'idempotence, qui evite les doubles credits (jusqu'a 1 a 2 % des cas). Repondez en moins de 5 secondes et conservez les logs 90 jours et plus.
Les quatre controles indispensables
Un webhook robuste empile quatre defenses. Chacune bloque une attaque ou une erreur precise.
| Controle | Attaque bloquee | Cout d'implementation | Priorite |
|---|---|---|---|
| Signature HMAC | Faux callback | Faible | Critique |
| Idempotence (ID unique) | Double credit | Faible | Critique |
| Liste blanche IP | Requetes hors PSP | Moyen | Elevee |
| Anti-rejeu (timestamp) | Rejeu d'un vrai callback | Faible | Elevee |
| Verification releve | Paiement fantome | Moyen | Elevee |
La signature HMAC compare un hash calcule avec le secret partage : si le hash ne correspond pas, la requete est rejetee avant tout traitement.
Regles de reponse et de journalisation
Le comportement de reponse conditionne la fiabilite. Un webhook mal repondu declenche des retries et des doublons.
| Regle | Valeur cible 2026 | Pourquoi |
|---|---|---|
| Delai de reponse | < 5 s | Evite les retries du PSP |
| Code succes | 200 systematique | Stoppe la file de retry |
| Traitement asynchrone | File d'attente | Repondre vite, traiter apres |
| Tolerance timestamp | 5 min | Bloque le rejeu tardif |
| Retention des logs | 90+ jours | Preuve et debug litiges |
| Deduplication | Par ID transaction | 1-2 % de doubles evites |
Bonne pratique : accusez reception (200) immediatement, puis traitez la commande dans une file asynchrone. Ne bloquez jamais la reponse 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, developpeuse pour une boutique a Thies, recoit un signalement : deux clients ont ete livres sans avoir paye. Enquete : son endpoint acceptait tout POST sans verifier la signature. Un plaisantin avait rejoue un vrai callback. Correctif en une journee : verification HMAC (rejet des signatures invalides), idempotence par ID de transaction (les 2 doublons du mois disparaissent), et tolerance de timestamp a 5 minutes contre le rejeu. Sur 1 800 webhooks/mois, elle bloque desormais une dizaine de requetes suspectes et zero double credit. Cout : une journee de dev, contre des centaines de milliers de FCFA de marchandise offerte evitee.
FAQ
Qu'est-ce qu'une signature HMAC ? C'est un hash calcule a partir du corps du message et d'un secret partage avec le PSP. Vous recalculez ce hash a reception : s'il differe, le callback est faux et doit etre rejete avant tout traitement.
Pourquoi l'idempotence est-elle critique ? Parce que les PSP renvoient parfois le meme callback (retry). Sans deduplication par ID de transaction, vous creditez deux fois la commande dans 1 a 2 % des cas, faussant stock et comptabilite.
Faut-il une liste blanche d'IP ? C'est un bon complement, mais pas suffisant seul car les IP des PSP changent. Combinez-la avec la signature HMAC, qui reste la defense 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 reconciliation des paiements manquants.
Que faire si mon webhook est lent ? Repondez 200 en moins de 5 secondes puis traitez en file asynchrone. Un endpoint lent declenche des retries du PSP et multiplie les risques de doublons.
Discutons de votre projet. Nous securisons vos endpoints de paiement avec signature, idempotence et logs traces. 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.
