Webhooks expliqués : signatures et retries fiables

Backend2026-11-11TryQuickToolBox

Vous déployez une intégration de paiement et tout fonctionne en staging. Puis en production, un client paie, votre endpoint expire après deux secondes et la commande ne s'active jamais. Pendant ce temps, le fournisseur de paiement réessaie le même événement trois fois, et votre application crée trois commandes en double pour celle qui a réussi. Les webhooks semblent simples — juste un POST HTTP — mais les points délicats sont la confiance et les garanties de livraison.

Cet article couvre les deux choses qui cassent le plus souvent les intégrations webhook : vérifier qu'une requête provient bien de l'expéditeur, et gérer les retries sans dupliquer les effets de bord.

Ce qu'est réellement un webhook

Un webhook est un appel API inversé. Au lieu que votre serveur interroge le fournisseur toutes les minutes pour demander « du nouveau ? », le fournisseur pousse une requête HTTP vers une URL que vous avez enregistrée lorsqu'un événement se produit. Le payload est généralement du JSON, et le type d'événement se trouve soit dans le corps, soit dans un en-tête.

POST /webhooks/payments HTTP/1.1
Host: api.example.com
Content-Type: application/json
X-Event-Id: evt_8f2c1a
X-Timestamp: 1735689600
X-Signature: t=1735689600,v1=5d41402abc4b2a76b9719d911017c592

{
  "id": "evt_8f2c1a",
  "type": "payment.succeeded",
  "created": 1735689600,
  "data": { "order_id": "ord_123", "amount": 4999, "currency": "USD" }
}

Deux décisions de conception comptent côté expéditeur et vous devez vérifier les deux lors de l'évaluation d'un fournisseur : signe-t-il le payload, et réessaie-t-il en cas d'échec ?

Pourquoi les webhooks non signés sont dangereux

L'URL de votre webhook est publique. Quiconque l'apprend peut envoyer un faux événement payment.succeeded et marquer une commande impayée comme payée. Une liste blanche d'IP aide un peu, mais les fournisseurs changent d'IP, opèrent derrière des CDN, et vous n'obtiendrez peut-être pas de liste stable.

La solution robuste est une signature HMAC sur le corps brut de la requête, utilisant un secret partagé que seuls vous et le fournisseur connaissez. Le fournisseur calcule la signature et l'envoie dans un en-tête ; vous la recalculez et la comparez.

Vérifier correctement une signature

Trois détails sont faciles à rater :

// Exemple Node.js / Express
const crypto = require('crypto');

function verifySignature(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(
    header.split(',').map(p => p.split('='))
  );
  const timestamp = Number(parts.t);
  if (!timestamp) return false;

  // Rejeter les requêtes obsolètes (protection contre le rejeu)
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - timestamp) > toleranceSeconds) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${parts.t}.${rawBody}`)
    .digest('hex');

  const a = Buffer.from(expected);
  const b = Buffer.from(parts.v1 || '');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

app.post('/webhooks/payments', express.raw({ type: '*/*' }), (req, res) => {
  if (!verifySignature(req.body.toString(), req.get('X-Signature'), SECRET)) {
    return res.status(401).send('invalid signature');
  }
  const event = JSON.parse(req.body.toString());
  // ... traiter l'événement
  res.status(200).send('ok');
});

Notez le middleware express.raw(). Si vous montez express.json() avant cette route, le corps est déjà parsé et la vérification de signature échoue silencieusement — un bug très courant.

Concevoir des retries qui ne perdent pas d'événements

La livraison de webhooks est at-least-once, pas exactly-once. Les réseaux échouent, votre déploiement redémarre un conteneur, et le fournisseur n'a aucune idée si votre réponse 200 était réelle. Donc le fournisseur réessaie avec un backoff exponentiel, souvent pendant des heures ou des jours.

Répondez vite, traitez plus tard

Votre endpoint doit faire le minimum : vérifier, persister l'événement brut, renvoyer 2xx. Le travail lourd — envoyer des e-mails, appeler d'autres API, générer des factures — doit se faire dans un job en arrière-plan. Si le traitement prend plus de temps que le timeout du fournisseur, la requête est considérée comme échouée et réessayée même si vous avez fait le travail.

  1. Vérifiez la signature et le timestamp.
  2. Insérez l'événement dans une table avec une contrainte d'unicité sur l'ID d'événement.
  3. Renvoquez 200 immédiatement.
  4. Traitez l'événement stocké de manière asynchrone, en le marquant comme terminé.

Idempotence : la vraie solution contre les doublons

Parce que les retries existent, votre handler doit pouvoir s'exécuter deux fois sans problème. L'ID d'événement est la clé d'idempotence naturelle.

INSERT INTO webhook_events (event_id, type, payload, received_at)
VALUES ($1, $2, $3, now())
ON CONFLICT (event_id) DO NOTHING;

Si l'insertion affecte zéro ligne, vous avez déjà vu cet événement — accusez réception et passez à la suite. Pour la logique métier, appliquez la même idée : utilisez l'ID de commande comme clé unique lors de l'activation d'un paiement, afin qu'un second événement ne puisse pas créer une seconde activation.

Choisir les codes de statut intentionnellement

StatutComportement du fournisseurQuand l'utiliser
200 / 204Marqué comme livréÉvénement accepté (même si déjà traité)
400Généralement pas de retryPayload malformé que vous ne pourrez jamais traiter
401Généralement pas de retrySignature incorrecte — vérifiez votre secret
429Retry avec backoffVous limitez le débit
500 / 503Retry avec backoffÉchec temporaire, base de données en panne, déploiement en cours

Renvoyer 200 pour un événement que vous n'avez pas pu stocker est la pire option : le fournisseur arrête de réessayer et l'événement est perdu à jamais. Renvoyez un 5xx et laissez le retry faire son travail.

Checklist pratique pour la production

Tester les webhooks en local

Vous ne pouvez pas facilement recevoir un POST public sur localhost. Options : un outil de tunneling qui expose votre port de dev, la CLI du fournisseur si elle existe, ou un petit script qui envoie un payload signé à votre handler pour exercer le chemin de vérification.

Le test le plus précieux est le doublon : envoyez le même événement deux fois et confirmez que votre système aboutit au même état. Ensuite, envoyez un événement avec un timestamp ancien et confirmez qu'il est rejeté. Puis modifiez un octet du corps et confirmez que la vérification de signature échoue.

Déboguer les payloads

Les corps de webhook sont du JSON, et les payloads malformés ou profondément imbriqués sont pénibles à lire dans les logs. Un formateur vous aide à inspecter la structure rapidement avant d'écrire du code de parsing. Le formateur JSON s'exécute dans le navigateur, donc vous pouvez coller un payload capturé sans envoyer de données client à un serveur.

FAQ

Quelle est la différence entre un webhook et une API ?

Une API est basée sur le pull : votre code appelle le fournisseur quand il a besoin de données. Un webhook est basé sur le push : le fournisseur appelle votre endpoint quand un événement se produit. La plupart des intégrations utilisent les deux — les webhooks pour les notifications d'événements et l'API pour récupérer les détails complets ou effectuer des actions.

Pourquoi ma signature HMAC ne correspond-elle jamais ?

La cause habituelle est de signer un corps re-sérialisé au lieu des octets bruts. Les espaces, l'ordre des clés et l'échappement unicode modifient tous le hash. Lisez le corps brut de la requête avant tout middleware JSON, et confirmez que le secret et l'algorithme de hash correspondent à la documentation du fournisseur.

Les retries de webhook sont-ils garantis ?

Non. Les fournisseurs réessaient généralement pendant une fenêtre limitée avec un backoff exponentiel, puis abandonnent. Traitez les webhooks comme un canal de notification rapide plutôt qu'une source de vérité : réconciliez périodiquement avec l'API du fournisseur pour que les événements manqués soient finalement corrigés.

Si vous construisez ou déboguez un récepteur de webhook aujourd'hui, commencez par verrouiller la vérification de signature et le stockage idempotent — ces deux changements éliminent la majorité des incidents webhook réels.