Webhooks expliqués : signatures et retries fiables
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 :
- Utilisez le corps brut. Ne parsez le JSON qu'après vérification. Re-sérialiser un objet parsé modifie les espaces et l'ordre des clés, donc la signature ne correspondra jamais.
- Comparez en temps constant. Une comparaison de chaînes naïve fuit des informations de timing. Utilisez une fonction à temps constant.
- Incluez le timestamp dans la chaîne signée. Signer
timestamp.bodyvous permet de rejeter les requêtes anciennes et bloque les attaques par rejeu.
// 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.
- Vérifiez la signature et le timestamp.
- Insérez l'événement dans une table avec une contrainte d'unicité sur l'ID d'événement.
- Renvoquez
200immédiatement. - 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
| Statut | Comportement du fournisseur | Quand l'utiliser |
|---|---|---|
| 200 / 204 | Marqué comme livré | Événement accepté (même si déjà traité) |
| 400 | Généralement pas de retry | Payload malformé que vous ne pourrez jamais traiter |
| 401 | Généralement pas de retry | Signature incorrecte — vérifiez votre secret |
| 429 | Retry avec backoff | Vous limitez le débit |
| 500 / 503 | Retry 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
- Utilisez uniquement HTTPS ; n'acceptez jamais de webhooks en HTTP simple.
- Stockez le secret de signature dans votre gestionnaire de secrets et supportez la rotation — de nombreux fournisseurs permettent deux secrets actifs.
- Journalisez l'ID d'événement, le type, le résultat de la signature et le résultat du traitement pour chaque requête.
- Définissez une fenêtre de tolérance (cinq minutes est typique) pour bloquer les rejeux.
- Rendez les handlers idempotents au niveau de la base de données, pas seulement dans le code applicatif.
- Alertez lorsque le taux d'échec ou le retard de traitement dépasse un seuil.
- Fournissez un endpoint de rejeu manuel pour le support.
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.