Webhooks expliqués : charges utiles signées et stratégies de réessai
Vous avez construit une API qui envoie des webhooks pour notifier des services externes d'événements. Mais que se passe-t-il lorsque le point de terminaison récepteur est indisponible ? Ou lorsqu'un acteur malveillant tente de falsifier une requête webhook ? Sans protections adéquates, vos webhooks peuvent devenir une source d'incohérence des données et de vulnérabilités de sécurité. Cet article explique comment mettre en œuvre des charges utiles signées et des mécanismes de réessai pour rendre vos webhooks fiables et sécurisés.
Que sont les webhooks et pourquoi ont-ils besoin de sécurité ?
Les webhooks sont des callbacks HTTP définis par l'utilisateur, déclenchés par des événements spécifiques. Ils permettent une communication en temps réel entre systèmes, par exemple notifier un service de paiement lorsqu'une commande est passée. Cependant, comme les webhooks sont des points de terminaison accessibles publiquement, ils sont vulnérables à l'usurpation d'identité et aux attaques par rejeu. De plus, des problèmes réseau ou l'indisponibilité du récepteur peuvent entraîner des événements manqués. Par conséquent, deux aspects critiques doivent être traités : l'authenticité (via des charges utiles signées) et la fiabilité (via des réessais).
Charges utiles signées : garantir l'authenticité et l'intégrité
Une charge utile signée permet au récepteur de vérifier que le webhook provient d'une source fiable et que les données n'ont pas été altérées. Cela est généralement réalisé à l'aide de HMAC (Hash-based Message Authentication Code) avec un secret partagé.
Comment fonctionne la signature HMAC
L'expéditeur et le récepteur partagent une clé secrète. Pour chaque requête webhook, l'expéditeur calcule une signature HMAC en utilisant le secret et la charge utile de la requête (incluant souvent un horodatage pour prévenir les attaques par rejeu). La signature est envoyée dans un en-tête, tel que X-Signature. Le récepteur recalcule la signature et la compare avec celle reçue. Si elles correspondent, la requête est authentique.
Voici un exemple en Python utilisant HMAC-SHA256 :
import hmac
import hashlib
import time
secret = b'your_shared_secret'
payload = b'{"event":"order.created","id":123}'
timestamp = str(int(time.time())).encode()
message = timestamp + b'.' + payload
signature = hmac.new(secret, message, hashlib.sha256).hexdigest()
# Envoyer les en-têtes : X-Signature: signature, X-Timestamp: timestamp
Du côté du récepteur, vérifiez la signature et contrôlez l'horodatage pour vous assurer que la requête est récente (par exemple, dans les 5 minutes). Cela empêche les attaques par rejeu.
Bonnes pratiques pour les charges utiles signées
- Utilisez un secret fort : Générez un secret aléatoire à haute entropie et stockez-le en toute sécurité.
- Incluez un horodatage : Rejetez les requêtes dont l'horodatage est en dehors d'une fenêtre acceptable.
- Utilisez une comparaison à temps constant : Prévoyez les attaques temporelles en utilisant des fonctions comme
hmac.compare_digest. - Faites tourner les secrets périodiquement : Autorisez plusieurs secrets actifs pendant la rotation.
Mécanismes de réessai : garantir une livraison fiable
Même avec des charges utiles signées, des défaillances réseau ou des erreurs du récepteur peuvent entraîner l'échec de la livraison des webhooks. Une stratégie de réessai robuste garantit que les événements sont finalement livrés sans submerger le récepteur.
Concevoir une politique de réessai
Une approche courante consiste à utiliser un backoff exponentiel avec jitter. Par exemple, réessayez après 1 minute, puis 5 minutes, puis 30 minutes, jusqu'à un nombre maximal de tentatives (par exemple, 5). Incluez un ID d'événement unique dans la charge utile pour que le récepteur puisse dédupliquer.
Exemple de calendrier de réessai :
| Tentative | Délai |
|---|---|
| 1 | Immédiat |
| 2 | 1 minute |
| 3 | 5 minutes |
| 4 | 30 minutes |
| 5 | 2 heures |
Après avoir épuisé les réessais, déplacez l'événement vers une file d'attente de messages morts pour une inspection manuelle.
Idempotence : gérer les livraisons en double
Étant donné que les réessais peuvent entraîner des livraisons en double, les récepteurs doivent être idempotents. Incluez un ID d'événement dans la charge utile et demandez au récepteur de stocker les ID traités pour ignorer les doublons. Alternativement, concevez des opérations naturellement idempotentes (par exemple, en utilisant PUT au lieu de POST).
Implémenter des webhooks : un guide étape par étape
- Définissez les événements et la structure de la charge utile : Documentez les événements que votre système émet et le schéma JSON pour chacun.
- Générez un secret : Créez un secret unique par point de terminaison webhook et partagez-le en toute sécurité.
- Signez chaque requête : Calculez le HMAC sur la charge utile et l'horodatage, incluez-le dans les en-têtes.
- Implémentez des réessais avec backoff : Utilisez un système de file d'attente pour planifier les réessais.
- Fournissez un moyen de vérifier les signatures : Documentez le processus de vérification pour les récepteurs.
- Surveillez et journalisez : Suivez les tentatives de livraison et les échecs pour le débogage.
Pièges courants et comment les éviter
- Ignorer TLS : Utilisez toujours HTTPS pour protéger les charges utiles en transit.
- Ne pas valider l'horodatage : Permet les attaques par rejeu.
- Réessayer indéfiniment : Peut entraîner un épuisement des ressources ; fixez un maximum.
- Supposer une livraison immédiate : Concevez pour un traitement asynchrone.
FAQ
Qu'est-ce qu'une charge utile webhook signée ?
Une charge utile webhook signée inclut une signature cryptographique (par exemple, HMAC) qui permet au récepteur de vérifier l'authenticité de l'expéditeur et l'intégrité des données.
Combien de fois dois-je réessayer un webhook échoué ?
Typiquement 3 à 5 réessais avec un backoff exponentiel. Le nombre exact dépend de votre SLA et de la criticité de l'événement.
Puis-je utiliser JWT au lieu de HMAC pour les signatures de webhook ?
Oui, JWT peut être utilisé, mais HMAC est plus simple et plus courant pour la signature de webhooks. JWT ajoute une surcharge et est mieux adapté aux jetons d'authentification.
Prêt à tester vos charges utiles de webhook ? Utilisez notre formateur JSON pour valider et embellir vos charges utiles JSON avant l'envoi.