Webhooks expliqués : charges utiles signées et nouvelles tentatives
Pourquoi les webhooks échouent en production
Vous avez créé un point de terminaison webhook, testé localement, et tout fonctionne. Puis la production arrive : un fournisseur envoie un événement en double, votre point de terminaison expire, ou un attaquant usurpe une requête. Soudain, votre intégration est peu fiable et non sécurisée.
Les webhooks sont simples en concept—des rappels HTTP déclenchés par des événements—mais les implémentations de qualité production nécessitent une gestion attentive de la sécurité et de la fiabilité. Ce guide couvre deux aspects critiques : les charges utiles signées pour vérifier l'authenticité et les stratégies de nouvelle tentative pour gérer les échecs.
Que sont les webhooks ?
Un webhook est un rappel HTTP défini par l'utilisateur. Lorsqu'un événement se produit dans un système source (par exemple, un paiement réussi), il envoie une requête HTTP POST à une URL que vous fournissez, contenant des données sur l'événement. Ce modèle push est plus efficace que l'interrogation.
Mais les webhooks introduisent des défis :
- Sécurité : Comment savoir que la requête provient de l'expéditeur légitime ?
- Fiabilité : Et si votre point de terminaison est indisponible ou lent ?
- Doublons : Les réseaux peuvent provoquer des nouvelles tentatives ; vous pourriez recevoir le même événement plusieurs fois.
Abordons d'abord la sécurité.
Sécuriser les webhooks avec des charges utiles signées
Les charges utiles signées utilisent un secret partagé pour créer une signature cryptographique du corps de la requête. L'expéditeur inclut cette signature dans un en-tête (par exemple, X-Signature). Votre point de terminaison recalcule la signature et la compare. Si elles correspondent, la requête est authentique.
Comment fonctionne la signature HMAC
La plupart des fournisseurs utilisent HMAC-SHA256. La signature est calculée sur le corps brut de la requête en utilisant le secret partagé. Voici le déroulement :
- Le fournisseur et le consommateur partagent une clé secrète.
- Le fournisseur crée la charge utile, calcule HMAC-SHA256(secret, payload), et l'envoie dans un en-tête.
- Le consommateur reçoit la requête, lit le corps brut, calcule le même HMAC, et compare.
Important : Utilisez le corps brut exactement tel que reçu—l'analyse et la re-sérialisation du JSON peuvent modifier les octets et invalider la signature.
Implémentation de la vérification de signature
Voici un exemple Node.js avec Express :
const crypto = require('crypto');
const express = require('express');
const app = express();
// Utiliser un analyseur de corps brut pour les routes webhook
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
const signature = req.headers['x-signature'];
const secret = process.env.WEBHOOK_SECRET;
const expected = crypto
.createHmac('sha256', secret)
.update(req.body)
.digest('hex');
if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
return res.status(401).send('Invalid signature');
}
// Traiter l'événement
const event = JSON.parse(req.body);
// ... gérer l'événement
res.status(200).send('OK');
});
Utilisez toujours une comparaison à temps constant comme crypto.timingSafeEqual pour éviter les attaques temporelles.
Autres considérations de sécurité
- Validation de l'horodatage : Incluez un horodatage dans la charge utile signée et rejetez les requêtes anciennes pour éviter les attaques par rejeu.
- HTTPS : Utilisez toujours HTTPS pour les points de terminaison webhook.
- Rotation des secrets : Prenez en charge plusieurs secrets actifs pour permettre la rotation sans interruption de service.
Mettre en œuvre des nouvelles tentatives fiables
Même avec un point de terminaison sécurisé, des problèmes réseau ou des défaillances temporaires peuvent entraîner l'échec de la livraison des webhooks. Un mécanisme de nouvelle tentative robuste garantit que les événements ne sont pas perdus.
Stratégie de nouvelle tentative côté expéditeur
Si vous construisez un expéditeur de webhooks, implémentez un backoff exponentiel avec jitter. Par exemple :
- Nouvelle tentative 1 : après 1 minute
- Nouvelle tentative 2 : après 5 minutes
- Nouvelle tentative 3 : après 30 minutes
- Nouvelle tentative 4 : après 2 heures
- Nouvelle tentative 5 : après 24 heures
Ajoutez un jitter aléatoire pour éviter les problèmes de troupeau. Arrêtez après un nombre maximal de tentatives et alertez.
Meilleures pratiques côté destinataire
En tant que consommateur de webhooks, vous ne pouvez pas contrôler la politique de nouvelle tentative de l'expéditeur, mais vous pouvez rendre votre point de terminaison résilient :
- Répondez rapidement : Accusez réception avec un statut 2xx avant de traiter un travail lourd. Utilisez une file d'attente.
- Idempotence : Gérez les événements en double avec grâce. Utilisez l'ID de l'événement pour dédupliquer.
- Surveillez les échecs : Journalisez les échecs et configurez des alertes.
Gérer les doublons avec idempotence
Les fournisseurs de webhooks réessaient souvent en cas d'expiration, vous pouvez donc recevoir le même événement plusieurs fois. Rendez votre traitement idempotent :
- Stockez les ID d'événements traités dans une base de données avec une contrainte d'unicité.
- Avant de traiter, vérifiez si l'ID existe déjà ; si oui, retournez 200 OK sans retraitement.
- Pour les opérations modifiant l'état, utilisez des clés d'idempotence.
Exemple avec un index unique de base de données :
async function handleEvent(event) {
try {
await db.query('INSERT INTO processed_events (id) VALUES ($1)', [event.id]);
} catch (err) {
if (err.code === '23505') { // violation d'unicité
return; // déjà traité
}
throw err;
}
// traiter l'événement
}
Comparaison : Approches de sécurité des webhooks
| Approche | Avantages | Inconvénients |
|---|---|---|
| Signature HMAC | Forte intégrité, largement supportée | Nécessite la gestion des secrets |
| Authentification basique | Simple | Moins sécurisée, identifiants dans l'en-tête |
| Liste d'IP autorisées | Facile à mettre en œuvre | Les IP peuvent changer, pas robuste |
Les signatures HMAC sont la norme de facto pour la sécurité des webhooks.
Tester les webhooks localement
Des outils comme ngrok ou localtunnel exposent votre serveur local à Internet pour les tests. Testez toujours la vérification de signature et la logique de nouvelle tentative avec des échecs simulés.
Lors de l'inspection des charges utiles JSON des webhooks, les formater peut aider au débogage. Essayez notre JSON Formatter pour embellir et valider les charges utiles des webhooks.
FAQ
Comment vérifier une signature de webhook ?
Calculez un HMAC du corps brut de la requête en utilisant le secret partagé, puis comparez-le à l'en-tête de signature à l'aide d'une fonction de comparaison à temps constant.
Que faire si mon point de terminaison webhook est indisponible ?
La plupart des fournisseurs réessaient avec un backoff exponentiel. Assurez-vous que votre point de terminaison retourne un 2xx rapidement et traitez de manière asynchrone pour minimiser l'impact des temps d'arrêt.
Puis-je utiliser des webhooks sans signatures ?
C'est risqué. Sans signatures, les attaquants peuvent usurper des requêtes. Utilisez toujours des charges utiles signées ou au moins une authentification basique sur HTTPS.
Conclusion
Les webhooks sont puissants mais nécessitent une attention particulière à la sécurité et à la fiabilité. Implémentez la vérification de signature HMAC pour garantir l'authenticité, et concevez votre système pour gérer les nouvelles tentatives et les doublons avec grâce. Avec ces pratiques, vos intégrations de webhooks seront robustes et prêtes pour la production.