## Un endpoint ouvert aux notifications du monde entier Les webhooks automatisent l'intégration entre services en poussant un événement vers votre URL dès qu'il se produit. Côté réception, vous exposez pourtant un point d'entrée HTTP que n'importe qui peut tenter d'appeler. La documentation Stripe sur les signatures rappelle qu'il faut vérifier chaque payload avant de le traiter. Sans signature, idempotence et politique de retries, vous cumulez risques d'abus, doublons et pertes silencieuses d'événements. ## Signature, idempotence et retries en bref La signature HMAC prouve que le corps du message n'a pas été modifié et qu'il provient de l'émetteur attendu. Un même événement reçu deux fois ne doit produire qu'un seul effet métier (paiement, expédition, activation de compte). L'émetteur réessaie après un échec. Votre endpoint doit répondre vite et de façon prévisible pour éviter les tempêtes de relances. Commencez par valider la signature sur un seul fournisseur (Stripe, GitHub, etc.), puis stockez l'identifiant d'événement avant tout effet de bord irréversible. ## Mise en pratique des signatures La signature des webhooks repose en général sur HMAC (Hash-based Message Authentication Code) : l'émetteur hache le corps brut de la requête avec une clé secrète partagée. À la réception, vous recalculez le digest et le comparez à l'en-tête fourni (par exemple `Stripe-Signature` ou `X-Hub-Signature-256`). La validation des livraisons GitHub illustre ce schéma avec SHA-256. 1. **Génération de la clé secrète** : une clé par intégration, stockée côté serveur (variable d'environnement ou coffre). 2. **Corps brut** : ne parsez pas le JSON avant de vérifier la signature. Utilisez le buffer exact reçu. 3. **Fenêtre temporelle** : rejeter les payloads trop anciens limite les attaques par rejeu. ## Idempotence : éviter les effets de bord L'idempotence garantit qu'un webhook dupliqué ne déclenche pas deux fois la même action. Les émetteurs réémettent souvent le même événement après un timeout ou une réponse ambiguë. - **Identifiant unique** : persister `event_id` (ou équivalent) avant tout traitement long. - **État de traitement** : marquer `received`, `processed`, `failed` pour refuser proprement un doublon. - **Réponse HTTP** : renvoyer `200` si l'événement est déjà traité, pas une erreur qui provoquerait de nouveaux retries. Les bonnes pratiques API de l'OWASP REST Security Cheat Sheet s'appliquent aussi aux endpoints de callback. ## Gestion des retries : garantir la fiabilité Les échecs réseau ou un handler trop lent poussent l'émetteur à relancer la livraison. Votre code doit rester court : valider, enfiler en file (queue) ou worker, répondre rapidement. 1. **Politique côté émetteur** : délais exponentiels, plafond de tentatives, journal des échecs définitifs. 2. **Réponses stables** : `2xx` seulement quand le message est accepté ou déjà traité, `5xx` uniquement si vous voulez une relance. 3. **Alerte** : notifier l'équipe quand un événement critique échoue après le dernier retry. L'architecture event-driven de Microsoft Learn décrit comment découpler réception et traitement pour absorber ces pics. ## Checklist pour l'implémentation des webhooks sécurisés - **Configurer la signature HMAC** : vérifier le corps brut avec la clé du fournisseur. - **Implémenter l'idempotence** : clé unique par événement, état persisté avant effet de bord. - **Définir une politique de retries** : réponse rapide, traitement asynchrone si besoin. - **Tester les scénarios** : payload invalide, doublon, timeout simulé, rejeu hors fenêtre temporelle. ## Pour aller plus loin sur le blog Découvrez d'autres articles sur le sujet : Monitoring applicatif : Sentry et OpenTelemetry en pratique et Node.js : le runtime JavaScript côté serveur. ## Sources - Stripe. Vérification des signatures webhook - GitHub. Valider les livraisons de webhooks - OWASP. REST Security Cheat Sheet - Microsoft Learn. Architecture event-driven Des webhooks bien signés, idempotents et tolérants aux retries réduisent les incidents en production et simplifient le diagnostic quand un partenaire signale un événement manquant.

#api

Webhooks sécurisés : signature, idempotence et retries