Webhooks expliqués : charges utiles signées et nouvelles tentatives

Backend2026-11-15TryQuickToolBox

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 :

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 :

  1. Le fournisseur et le consommateur partagent une clé secrète.
  2. Le fournisseur crée la charge utile, calcule HMAC-SHA256(secret, payload), et l'envoie dans un en-tête.
  3. 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é

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 :

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 :

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 :

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.