Webhooks expliqués : payloads signés et retries fiables

Vous venez d'intégrer une passerelle de paiement tierce ou un service CI/CD, et vous avez besoin de notifications en temps réel. Les webhooks sont la solution—mais sans sécurité ni fiabilité adéquates, ils peuvent devenir une source de frustration. Des attaquants peuvent usurper des requêtes, et des incidents réseau peuvent entraîner des événements manqués. Dans ce guide, nous allons voir comment sécuriser les webhooks avec des payloads signés et mettre en place des mécanismes de retry robustes.

Que sont les webhooks ?

Les webhooks sont des callbacks HTTP définis par l'utilisateur, déclenchés par des événements spécifiques. Lorsqu'un événement se produit (par exemple, un paiement réussi), le service source envoie une requête HTTP POST à une URL que vous fournissez, contenant les données de l'événement. Ce modèle push est plus efficace que le polling et permet des réactions en temps réel.

Cependant, les webhooks introduisent deux défis : l'authenticité (s'assurer que la requête provient de l'expéditeur attendu) et la fiabilité (s'assurer de ne pas manquer d'événements).

Sécuriser les webhooks avec des payloads signés

Un payload signé utilise un secret partagé entre l'expéditeur et le destinataire pour créer une signature cryptographique. L'expéditeur inclut cette signature dans un en-tête, et le destinataire la vérifie pour confirmer l'intégrité et l'origine du payload.

Comment fonctionne la signature HMAC

HMAC (Hash-based Message Authentication Code) est l'approche standard. L'expéditeur calcule un HMAC sur le corps de la requête en utilisant le secret partagé et l'inclut dans un en-tête comme X-Signature. Le destinataire recalcule le HMAC et le compare.

// Exemple : génération d'une signature en Node.js
const crypto = require('crypto');

function generateSignature(payload, secret) {
  return crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
}

// Côté réception, vérification :
function verifySignature(payload, secret, receivedSignature) {
  const expected = generateSignature(payload, secret);
  // Utiliser une comparaison à temps constant pour éviter les attaques temporelles
  return crypto.timingSafeEqual(
    Buffer.from(expected, 'hex'),
    Buffer.from(receivedSignature, 'hex')
  );
}

Points clés :

• Utilisez toujours un secret fort et unique par endpoint de webhook.
• Comparez les signatures avec une fonction à temps constant pour éviter les fuites d'information.
• Incluez un timestamp dans la signature pour prévenir les attaques par rejeu (par exemple, signer timestamp + payload).

Mesures de sécurité supplémentaires

• HTTPS : Utilisez toujours HTTPS pour chiffrer les données en transit.
• Allowlisting IP : Si le fournisseur publie des plages d'IP, limitez les requêtes entrantes à ces IP.
• Limites de taille des payloads : Rejetez les payloads trop volumineux pour atténuer les DoS.

Implémenter des retries fiables

Les réseaux ne sont pas fiables. Un webhook peut échouer à cause de timeouts, d'erreurs serveur ou de pannes temporaires. Une stratégie de retry robuste garantit une livraison éventuelle sans surcharger votre système ni l'expéditeur.

Bonnes pratiques de retry

1. Backoff exponentiel : Augmentez le délai entre les tentatives (par exemple, 1s, 2s, 4s, 8s...).
2. Limite maximale de retries : Plafonnez le nombre de tentatives (par exemple, 5) pour éviter les boucles infinies.
3. File de messages morts : Après épuisement des retries, stockez les événements échoués pour inspection manuelle.
4. Idempotency : Assurez-vous que le traitement du même événement plusieurs fois ne cause pas d'effets de bord en double.

L'idempotency en pratique

Incluez un ID d'événement unique dans le payload. Côté destinataire, suivez les IDs traités (dans une base de données ou un cache) et ignorez les doublons. Par exemple :

// Pseudocode pour un traitement idempotent
if (eventStore.exists(event.id)) {
  return 200; // Déjà traité
}
// Traitement de l'événement...
eventStore.save(event.id);

Gérer les échecs avec élégance

Répondez rapidement avec un statut 2xx pour accuser réception. Si le traitement prend du temps, mettez l'événement en file d'attente et traitez-le de manière asynchrone. Ne retournez 5xx que pour des erreurs transitoires qui justifient un retry ; pour les erreurs permanentes (par exemple, payload invalide), retournez 4xx pour éviter des retries inutiles.

Comparaison : Push vs Poll

Tester votre implémentation de webhook

Utilisez des outils comme ngrok pour exposer votre serveur local et simuler des livraisons de webhooks. Vérifiez la validation des signatures et le comportement des retries en provoquant volontairement des échecs de requêtes.

FAQ

Qu'est-ce qu'un payload de webhook signé ?

Un payload signé inclut une signature cryptographique (souvent HMAC) qui permet au destinataire de vérifier l'authenticité et l'intégrité de la requête grâce à un secret partagé.

Combien de fois faut-il retenter un webhook échoué ?

Il n'y a pas de nombre universel, mais 3 à 5 retries avec backoff exponentiel sont courants. Ensuite, journalisez l'échec pour une revue manuelle.

Peut-on utiliser des webhooks sans HTTPS ?

Techniquement oui, mais c'est très peu sécurisé. Utilisez toujours HTTPS pour prévenir l'écoute clandestine et les attaques de type man-in-the-middle.

Prêt à inspecter des payloads de webhooks ? Utilisez notre formateur JSON pour pretty-printer et valider rapidement des payloads JSON.