Webhook
Définition
URL exposée par votre application pour recevoir des événements en temps réel depuis un service tiers (paiement Stripe, formulaire, n8n). L'inverse d'une API classique : c'est le service qui appelle votre URL.
Comment ça marche
Un webhook est une URL que votre application expose publiquement pour recevoir des notifications poussées par un service tiers. Quand un événement se produit chez le service (paiement réussi, formulaire envoyé, lead créé, commit poussé), il déclenche un POST HTTP sur votre URL avec les données de l'événement au format JSON. Vous traitez cette notification de votre côté : enregistrement en base, déclenchement d'un workflow, envoi d'e-mail. C'est l'inverse d'une API que vous interrogez : vous n'allez pas chercher l'information, elle vient à vous.
À quoi ça sert
Les webhooks sont indispensables pour réagir à des événements externes en temps réel : Stripe pour les paiements et les factures, n8n ou Make pour les automatisations, un CRM pour synchroniser un nouveau prospect, GitHub pour déclencher un déploiement, un CMS pour invalider le cache d'un site Next.js. Sans webhook, on serait obligé de poller le service toutes les minutes pour vérifier les changements, ce qui coûterait des appels API inutiles et introduirait du retard. Le webhook est l'architecture standard pour les intégrations événementielles modernes.
Sécuriser un webhook
Une URL de webhook est publique : n'importe qui peut tomber dessus et envoyer des données factices. On sécurise systématiquement avec une signature : le service tiers signe le payload avec une clé secrète partagée, et inclut la signature dans un en-tête. Votre handler vérifie la signature avant tout traitement. Stripe utilise stripe-signature, GitHub utilise X-Hub-Signature-256, et chaque service a sa propre convention documentée. Sans cette vérification, un attaquant peut déclencher arbitrairement vos workflows internes. C'est une faille classique sur les premiers projets.
L'idempotence
Un même événement peut arriver plusieurs fois : retry automatique du service tiers, problème réseau, bug temporaire. Si votre handler envoie un e-mail à chaque réception, l'utilisateur peut recevoir trois fois la même confirmation. On garantit l'idempotence en stockant l'ID unique de l'événement (fourni par le service) et en refusant les doublons : si on a déjà traité l'événement evt_abc123, on répond 200 sans rien faire. Sans cette discipline, les webhooks produisent des effets secondaires en cascade dès que le réseau hoquette.
Logger et monitorer
Un webhook qui plante silencieusement peut perdre des transactions sans qu'on s'en rende compte pendant des semaines. On logge chaque réception (ID, source, timestamp, statut de traitement) dans une table dédiée, ce qui permet de rejouer en cas de bug. On monitore le taux d'erreur, le temps de traitement, et on configure une alerte si plus de quelques pour cent échouent. Stripe et GitHub renvoient des erreurs vers leur dashboard si votre endpoint répond mal, ce qui aide. On vise toujours une réponse HTTP rapide (sous 5 secondes) et on déporte le traitement lourd dans une queue asynchrone.
Les pièges à éviter
Quatre pièges classiques. Faire du traitement lourd dans le handler synchrone : le service tiers timeout et marque l'envoi en erreur, ce qui déclenche des retries. Oublier de retourner un code 2xx : le service considère que ça a échoué et renvoie. Stocker le secret de signature dans le code plutôt que dans les variables d'environnement. Tester en local sans tunnel ngrok ou Cloudflare Tunnel, ce qui empêche de reproduire le comportement réel. Pour le debug, les services proposent généralement un mode test avec replay des événements depuis leur dashboard.