Qu'est-ce qu'un webhook ?
Un webhook est un appel automatique, envoyé par un logiciel vers une adresse web que vous lui avez indiquée, chaque fois qu'un événement que vous avez choisi se produit. Le mot associe web et hook, le crochet : en programmation, un hook est un point d'accroche où l'on branche son propre traitement. Le webhook est ce point d'accroche, accessible par internet.
L'analogie la plus parlante est celle du colis attendu. Sans webhook, vous appelez le transporteur toutes les heures pour demander si le colis est livré, et la réponse est presque toujours non. Avec un webhook, le transporteur vous envoie un message au moment de la livraison, et seulement à ce moment-là. Le W3C s'appuie d'ailleurs sur ce mécanisme : sa recommandation WebSub, qui organise la diffusion de contenus entre éditeurs et abonnés, repose sur des web hooks HTTP.
Webhook ou API : quelle différence ?
La différence tient à qui prend l'initiative : avec une API, c'est le programme qui a besoin de l'information ; avec un webhook, c'est le logiciel où l'événement se produit.
| Appel d'API | Webhook | |
|---|---|---|
| Initiative | Votre programme, quand il en a besoin | Le logiciel source, quand l'événement survient |
| Fréquence | À la demande ou à intervalle fixe | À chaque événement, et seulement alors |
| Réactivité | Dépend de la fréquence d'interrogation | Proche du temps réel |
| Côté destinataire | Rien à ouvrir sur internet | Une adresse de réception publique et protégée |
| Risque principal | Interrogations inutiles, limites d'appels atteintes | Événements manqués si le destinataire est hors service |
Les deux se combinent souvent : le webhook signale que la facture est payée, puis le programme appelle l'API pour récupérer le détail. La documentation de Stripe suggère d'ailleurs d'utiliser l'API pour récupérer un objet manquant quand les événements arrivent dans le désordre.
Comment fonctionne un webhook, étape par étape ?
- Abonnement : dans le logiciel source, on déclare une adresse de réception et la liste des événements à suivre.
- Événement : un client paie ; le logiciel source fabrique un message qui décrit ce paiement.
- Envoi : le message part en requête HTTP vers l'adresse déclarée, accompagné d'une signature.
- Accusé de réception : le destinataire répond aussitôt par un code de succès, puis traite le message. GitHub demande une réponse en moins de 10 secondes, faute de quoi la livraison est considérée comme un échec.
- Nouvelles tentatives : en cas d'échec, l'émetteur réessaie. En production, Stripe retente la livraison pendant trois jours au maximum, avec des intervalles de plus en plus longs.
Exemples de webhooks dans une PME
- Paiement en ligne : le prestataire de paiement signale qu'une facture est réglée ; le logiciel de gestion la passe en payée et libère l'expédition.
- Signature électronique : le dernier signataire valide le contrat ; le CRM passe l'affaire en gagnée et ouvre le dossier client.
- Formulaire du site : une demande de devis arrive ; elle est créée dans le CRM et attribuée au commercial du secteur.
- Boutique en ligne : une commande est validée ; l'entrepôt reçoit le bon de préparation sans export manuel.
- Développement : un développeur pousse du code sur le dépôt ; la chaîne de CI/CD peut lancer les tests.
Pour un flux simple, un outil d'automatisation suffit souvent : n8n, Make et Zapier savent tous trois recevoir un webhook pour déclencher un scénario, et le comparatif n8n, Make ou Zapier aide à choisir. Pour un flux qui touche l'argent ou le stock, le récepteur se développe et se surveille comme une partie du logiciel, ce que décrit la page connecter ses logiciels par API.
Ce qu'un webhook fiable exige
Un webhook fiable repose sur cinq précautions, documentées par les grands émetteurs eux-mêmes.
- Vérifier la signature de chaque message. Stripe signe chaque événement dans un en-tête Stripe-Signature et rappelle que, sans vérification, un attaquant peut envoyer de faux événements pour déclencher une commande ou ouvrir un accès.
- Répondre vite, traiter ensuite : accuser réception, puis placer le message dans une file d'attente, comme le recommande GitHub.
- Écarter les doublons : Stripe indique qu'un même événement peut être reçu plusieurs fois et conseille d'enregistrer l'identifiant des événements déjà traités.
- Ne pas dépendre de l'ordre : Stripe ne garantit pas que les événements arrivent dans l'ordre où ils ont été générés.
- Prévoir un rattrapage : après une panne, relancer les livraisons manquées, comme le conseille GitHub, et compléter par une vérification périodique via l'API.
Une erreur classique consiste à traiter le webhook comme une preuve : c'est une notification rapide, pas un registre comptable. La référence reste la base de données, tenue selon vos propres règles.
Termes voisins
- Middleware : la couche intermédiaire qui reçoit les webhooks de plusieurs logiciels, les journalise et les redistribue.
- Interrogation périodique (polling) : la vérification à intervalle fixe, solution de repli quand un logiciel n'émet pas de webhook.
- File de messages : le réservoir où les événements attendent d'être traités, pour ne rien perdre lors d'un pic ou d'une panne.
- Événement : le fait métier (paiement, commande, signature) qui déclenche l'envoi d'un webhook.
Questions fréquentes
- Quelle est la différence entre un webhook et une API ?
- Une API répond quand on l'interroge, alors qu'un webhook prévient de lui-même quand un événement se produit. Avec une API, votre programme doit demander régulièrement s'il y a du nouveau ; avec un webhook, le logiciel source envoie un message à l'adresse que vous avez déclarée, au moment du paiement ou de la commande. Les deux se combinent souvent : le webhook signale l'événement, l'API fournit le détail.
- Un webhook est-il sécurisé ?
- Un webhook est sécurisé si le destinataire vérifie l'origine de chaque message. Les émetteurs sérieux signent leurs envois avec une clé secrète : Stripe place sa signature dans l'en-tête Stripe-Signature, et GitHub recommande un secret de webhook et une connexion HTTPS. Sans cette vérification, quiconque connaît l'adresse de réception peut envoyer de faux événements, comme un faux paiement validé.
- Que se passe-t-il si mon serveur est en panne quand le webhook arrive ?
- Si le serveur destinataire est indisponible, l'émetteur du webhook réessaie selon ses propres règles. Stripe retente la livraison pendant trois jours au maximum en production, avec des intervalles croissants ; GitHub recommande de relancer les livraisons manquées une fois le serveur rétabli. Une vérification de rattrapage par l'API, par exemple chaque nuit, récupère ce qui aurait été perdu.
- Peut-on recevoir des webhooks sans développer ?
- Oui, pour des flux simples. n8n propose un nœud Webhook qui démarre un workflow, Make crée des adresses de webhook qui déclenchent un scénario, et Zapier fournit l'application Webhooks by Zapier, classée parmi ses applications premium. Pour un flux qui engage de l'argent ou du stock, mieux vaut un récepteur développé, avec signature vérifiée, journal et reprise sur erreur.