Webhooks expliqués : charges utiles signées et réessais fiables
Vous venez d'intégrer un service tiers qui envoie des webhooks à votre point de terminaison. Tout fonctionne en test, mais en production, vous remarquez des événements manqués, des livraisons en double et même des requêtes falsifiées. Les webhooks sont simples en concept mais délicats à bien mettre en œuvre. Cet article explique comment sécuriser les webhooks avec des charges utiles signées et implémenter une logique de réessai fiable pour que vos intégrations soient robustes et dignes de confiance.
Que sont les webhooks et pourquoi ils importent
Les webhooks sont des callbacks HTTP définis par l'utilisateur, déclenchés par des événements. Au lieu d'interroger une API pour détecter des changements, vous enregistrez une URL, et le service envoie une requête POST avec les données de l'événement dès que quelque chose se produit. Ce modèle push réduit la latence et la charge serveur, ce qui le rend idéal pour les intégrations en temps réel comme les notifications de paiement, les déclencheurs CI/CD et les messages de chat.
Cependant, les webhooks introduisent des défis : vérifier l'authenticité, gérer les échecs et garantir un traitement exactement une fois. Abordons-les un par un.
Sécuriser les webhooks avec des charges utiles signées
Sans vérification, n'importe qui peut envoyer de fausses requêtes à votre point de terminaison webhook. Les charges utiles signées résolvent ce problème en incluant une signature cryptographique dans les en-têtes de la requête, générée à l'aide d'un secret partagé. Vous vérifiez la signature pour confirmer que la requête provient de l'expéditeur attendu et n'a pas été altérée.
Comment fonctionnent les signatures HMAC
La plupart des services utilisent HMAC (Hash-based Message Authentication Code) avec SHA-256. L'expéditeur calcule un hachage du corps de la requête (et parfois d'un horodatage) à l'aide du secret, et l'inclut dans un en-tête comme X-Signature. Vous recalculez le hachage de votre côté et comparez.
Voici un flux de vérification typique en Node.js :
const crypto = require('crypto');
function verifySignature(payload, signature, secret) {
const expected = crypto
.createHmac('sha256', secret)
.update(payload)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expected)
);
}
Utilisez toujours une comparaison à temps constant pour éviter les attaques temporelles. Incluez également un horodatage dans les données signées et rejetez les requêtes plus anciennes que quelques minutes pour prévenir les attaques par rejeu.
Bonnes pratiques pour la vérification de signature
- Utilisez HTTPS pour protéger la charge utile en transit.
- Stockez les secrets de manière sécurisée (par exemple, variables d'environnement, gestionnaires de secrets).
- Validez l'horodatage et rejetez les requêtes obsolètes.
- Journalisez les échecs de vérification pour la surveillance.
Implémenter des réessais fiables
Les réseaux échouent, les serveurs redémarrent et les points de terminaison expirent. Un système de webhooks robuste doit réessayer les livraisons échouées. Mais les réessais peuvent causer des doublons, vous avez donc besoin d'idempotence.
Stratégies de réessai
La plupart des fournisseurs utilisent un backoff exponentiel avec jitter. Par exemple, réessayer après 1 minute, puis 5 minutes, puis 30 minutes, jusqu'à un nombre maximum de tentatives (par exemple, 5). Incluez un ID d'événement unique dans la charge utile pour que le récepteur puisse dédupliquer.
Du côté récepteur, répondez rapidement avec un statut 2xx pour accuser réception, puis traitez de manière asynchrone. Si le traitement échoue, vous ne pouvez pas compter sur l'expéditeur pour réessayer indéfiniment—implémentez votre propre file d'attente de messages morts ou des alertes.
Clés d'idempotence
Pour gérer les livraisons en double, utilisez une clé d'idempotence (souvent l'ID d'événement) et stockez les ID traités pendant une période raisonnable. Avant le traitement, vérifiez si l'ID a déjà été vu ; si c'est le cas, retournez un succès sans retraiter.
// Exemple : vérification d'idempotence dans Express
app.post('/webhook', async (req, res) => {
const eventId = req.body.id;
if (await db.seenEvents.has(eventId)) {
return res.status(200).send('Already processed');
}
await db.seenEvents.add(eventId);
// traiter l'événement de manière asynchrone
res.status(200).send('OK');
});
Comparaison : Polling vs Webhooks
| Aspect | Polling | Webhooks |
|---|---|---|
| Latence | Élevée (basée sur un intervalle) | Faible (quasi temps réel) |
| Charge serveur | Élevée (requêtes fréquentes) | Faible (piloté par les événements) |
| Complexité | Simple à implémenter | Nécessite vérification de signature et réessais |
| Fiabilité | Dépend de la fréquence d'interrogation | Dépend du mécanisme de réessai |
Étape par étape : Construire un récepteur de webhook sécurisé
- Configurez un point de terminaison qui accepte les requêtes POST via HTTPS.
- Vérifiez la signature à l'aide du secret partagé et rejetez les requêtes invalides avec 401.
- Vérifiez l'horodatage pour prévenir les attaques par rejeu.
- Répondez immédiatement avec 200 OK après validation de base, puis traitez de manière asynchrone.
- Implémentez l'idempotence en utilisant les ID d'événement pour éviter le traitement en double.
- Journalisez et surveillez les échecs et les réessais.
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 l'authenticité et l'intégrité de la requête à l'aide d'un secret partagé.
Combien de fois dois-je réessayer un webhook échoué ?
La pratique courante est de 3 à 5 réessais avec un backoff exponentiel. Ensuite, déplacez l'événement vers une file d'attente de messages morts pour inspection manuelle.
Puis-je utiliser des webhooks sans HTTPS ?
Non, HTTPS est essentiel pour protéger la charge utile et la signature contre l'écoute et l'altération. Utilisez toujours TLS.
Prêt à tester vos charges utiles webhook ? Utilisez notre formateur JSON pour embellir et valider rapidement les charges utiles JSON.