Webhooks expliqués : charges utiles signées et réessais fiables

Backend2026-11-17TryQuickToolBox

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

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

AspectPollingWebhooks
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émenterNécessite vérification de signature et réessais
FiabilitéDépend de la fréquence d'interrogationDépend du mécanisme de réessai

Étape par étape : Construire un récepteur de webhook sécurisé

  1. Configurez un point de terminaison qui accepte les requêtes POST via HTTPS.
  2. Vérifiez la signature à l'aide du secret partagé et rejetez les requêtes invalides avec 401.
  3. Vérifiez l'horodatage pour prévenir les attaques par rejeu.
  4. Répondez immédiatement avec 200 OK après validation de base, puis traitez de manière asynchrone.
  5. Implémentez l'idempotence en utilisant les ID d'événement pour éviter le traitement en double.
  6. 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.