Webhooks expliqués : charges utiles signées et nouvelles tentatives
Vous venez d'intégrer un fournisseur de paiement ou un service CI/CD, et vous devez maintenant recevoir des événements en temps réel. Les webhooks sont la méthode standard pour pousser des données entre systèmes, mais de nombreuses implémentations échouent en production en raison de failles de sécurité ou d'une livraison peu fiable. Ce guide explique comment sécuriser les webhooks avec des charges utiles signées et mettre en œuvre des mécanismes de nouvelle tentative robustes.
Que sont les webhooks et pourquoi sont-ils importants
Un webhook est un rappel HTTP : lorsqu'un événement se produit dans un système source (par exemple, une nouvelle commande), il envoie une requête HTTP POST à une URL que vous fournissez. Contrairement au polling, les webhooks sont efficaces et quasi temps réel. Cependant, comme ils reposent sur HTTP, vous devez gérer explicitement la sécurité et la fiabilité.
Les cas d'utilisation courants incluent les notifications de paiement, les déclencheurs de pipeline CI/CD, les notifications de chat et la synchronisation de données entre applications SaaS.
Sécuriser les webhooks avec des charges utiles signées
Les webhooks sont des points de terminaison accessibles publiquement, les attaquants peuvent donc envoyer de fausses requêtes. Pour éviter cela, les fournisseurs signent chaque charge utile avec une clé secrète. Le récepteur vérifie la signature pour garantir l'authenticité et l'intégrité.
Comment fonctionnent les signatures HMAC
La méthode la plus courante est HMAC-SHA256. Le fournisseur calcule un hachage du corps de la requête à l'aide d'un secret partagé et l'inclut dans un en-tête (par exemple, X-Signature). Le récepteur recalcule le hachage et le compare.
// Exemple Node.js : génération d'une signature
const crypto = require('crypto');
const secret = 'your_webhook_secret';
const payload = JSON.stringify({ event: 'order.created', id: 123 });
const signature = crypto.createHmac('sha256', secret).update(payload).digest('hex');
// Envoyer la signature dans l'en-tête : X-Signature: sha256=...
Vérification des signatures côté récepteur
Utilisez toujours une comparaison à temps constant pour éviter les attaques temporelles. En Node.js, utilisez crypto.timingSafeEqual.
// Exemple de middleware Express.js
const crypto = require('crypto');
function verifySignature(req, res, next) {
const signature = req.headers['x-signature'];
const payload = JSON.stringify(req.body); // corps brut nécessaire
const expected = crypto.createHmac('sha256', secret).update(payload).digest('hex');
const trusted = Buffer.from(`sha256=${expected}`, 'utf8');
const received = Buffer.from(signature, 'utf8');
if (trusted.length !== received.length || !crypto.timingSafeEqual(trusted, received)) {
return res.status(401).send('Invalid signature');
}
next();
}
Important : Utilisez le corps brut de la requête pour la vérification, et non le JSON analysé, afin d'éviter les divergences.
Mesures de sécurité supplémentaires
- Validation de l'horodatage : Incluez un horodatage dans la signature et rejetez les requêtes datant de plus de quelques minutes pour prévenir les attaques par rejeu.
- HTTPS uniquement : Utilisez toujours des points de terminaison HTTPS pour protéger les données en transit.
- Liste blanche d'IP : Si le fournisseur publie des plages d'IP, limitez les requêtes entrantes à ces IP.
Mettre en œuvre des nouvelles tentatives fiables
Les webhooks peuvent échouer en raison de problèmes réseau, d'indisponibilité du serveur ou de bogues. Les fournisseurs réessaient généralement les livraisons échouées avec un backoff exponentiel. En tant que récepteur, vous devez être idempotent et gérer les événements en double.
Concevoir pour l'idempotence
Chaque événement webhook doit avoir un ID unique. Stockez les ID traités pour ignorer les doublons. Utilisez une base de données avec une contrainte d'unicité ou un cache comme Redis.
// Pseudocode pour un traitement idempotent
if (await redis.exists(`webhook:${event.id}`)) {
return res.status(200).send('Already processed');
}
await processEvent(event);
await redis.set(`webhook:${event.id}`, '1', 'EX', 86400); // TTL 24h
Stratégies de nouvelle tentative
Les fournisseurs réessaient généralement avec des délais croissants (par exemple, 1s, 5s, 30s, 5m, 1h). Assurez-vous que votre point de terminaison répond rapidement (dans les 5 secondes) pour éviter les délais d'attente. Si le traitement prend plus de temps, accusez réception et traitez de manière asynchrone.
Voici une comparaison des modèles de nouvelle tentative courants :
| Modèle | Avantages | Inconvénients |
|---|---|---|
| Intervalle fixe | Simple | Peut marteler un serveur en cours de récupération |
| Backoff exponentiel | Réduit la charge pendant les pannes | Livraison retardée pour les erreurs transitoires |
| Backoff exponentiel avec jitter | Prévient l'effet de troupeau | Légèrement plus complexe |
Surveillance et files d'attente de messages morts
Journalisez toutes les tentatives et échecs de webhooks. Après un nombre maximal de nouvelles tentatives, déplacez les événements vers une file d'attente de messages morts (DLQ) pour inspection manuelle. Alertez en cas de taux d'échec élevé.
Mise en pratique : une implémentation étape par étape
- Configurez un point de terminaison HTTPS qui accepte les requêtes POST et lit le corps brut.
- Vérifiez la signature à l'aide du secret partagé et d'une comparaison à temps constant.
- Vérifiez l'horodatage pour prévenir les attaques par rejeu (si fourni).
- Assurez l'idempotence en vérifiant l'ID de l'événement par rapport à un cache ou une base de données.
- Traitez l'événement de manière asynchrone s'il peut prendre du temps ; répondez immédiatement avec 200 OK.
- Implémentez une logique de nouvelle tentative côté expéditeur avec backoff exponentiel et jitter.
- Surveillez et alertez en cas d'échec, et utilisez une DLQ pour les erreurs persistantes.
FAQ
Qu'est-ce qu'une charge utile webhook signée ?
Une charge utile signée inclut une signature cryptographique (généralement HMAC) qui permet au récepteur de vérifier que la requête provient d'une source fiable et n'a pas été altérée.
Comment gérer les événements webhook en double ?
Utilisez l'ID d'événement unique fourni dans la charge utile pour suivre les événements traités. Stockez les ID dans une base de données ou un cache avec une TTL pour ignorer les doublons.
Que doit renvoyer mon point de terminaison webhook ?
Retournez rapidement un code de statut 2xx (par exemple, 200 OK) pour accuser réception. Si le traitement échoue, retournez un 5xx pour déclencher une nouvelle tentative, mais uniquement pour les erreurs transitoires.
Lorsque vous testez des charges utiles webhook, vous pouvez avoir besoin d'inspecter les structures JSON. Utilisez le JSON Formatter pour valider et embellir les charges utiles webhook afin de faciliter le débogage.