Ce qu'est un webhook
Un webhook est un mécanisme qui permet à un système d'envoyer automatiquement une notification à un autre système dès qu'un événement spécifique se produit. C'est une forme de communication entre applications qui fonctionne dans le sens inverse d'une API classique : plutôt que d'aller régulièrement interroger un service pour savoir si quelque chose a changé, on s'abonne à un événement et le service nous notifie instantanément quand il se produit.
L'analogie qui illustre le mieux la différence entre une API et un webhook est celle du suivi de colis. Aller sur le site du transporteur toutes les heures pour vérifier si le colis a été livré est l'équivalent d'un appel API régulier (polling). Recevoir un SMS automatique dès que le colis est déposé devant la porte est l'équivalent d'un webhook. Le webhook est plus efficace : il notifie immédiatement et sans consommer inutilement des ressources.
Techniquement, un webhook est une requête HTTP POST envoyée automatiquement par le système source vers une URL définie par le système de destination (appelée endpoint ou URL de webhook). Cette URL est un point d'entrée qui attend les notifications entrantes et les traite selon la logique définie.
Comment fonctionne un webhook en pratique
La mise en place d'un webhook suit généralement trois étapes.
La configuration côté émetteur. Dans l'interface du service qui va envoyer les webhooks (Stripe, Shopify, GitHub, un formulaire web), on déclare l'URL du endpoint qui recevra les notifications et on sélectionne les événements pour lesquels on veut être notifié. Stripe par exemple permet de souscrire à des dizaines d'événements distincts : paiement réussi, paiement échoué, abonnement créé, abonnement résilié, litige ouvert.
La création du endpoint récepteur. Côté receveur, on crée un endpoint HTTP qui attend les requêtes POST entrantes. Cet endpoint doit être accessible depuis internet (une URL publique), disponible en permanence et capable de traiter les notifications rapidement. Il répond généralement avec un code HTTP 200 pour confirmer la réception, ce qui indique à l'émetteur que la notification a bien été reçue.
Le traitement de la notification. Quand un webhook arrive, le endpoint lit les données envoyées dans le corps de la requête POST (généralement au format JSON) et déclenche la logique correspondante : créer une entrée en base de données, envoyer un email, mettre à jour un statut, déclencher une autre action dans un autre outil.
La sécurité des webhooks
Un endpoint de webhook est une URL publique accessible par n'importe qui. Sans mécanisme de sécurité, n'importe quelle requête POST vers cette URL serait traitée, ce qui ouvrirait la porte à des notifications falsifiées.
La plupart des services qui envoient des webhooks signent leurs notifications avec une clé secrète. Stripe par exemple calcule une signature HMAC-SHA256 du corps de la requête avec une clé secrète partagée et l'inclut dans les headers de la requête. Le endpoint récepteur recalcule cette signature et la compare : si elles ne correspondent pas, la notification est ignorée. C'est le mécanisme standard pour vérifier l'authenticité d'un webhook.
Il est également recommandé de traiter les webhooks de façon idempotente : le même webhook peut être envoyé plusieurs fois par le service émetteur en cas de doute sur la réception. Le endpoint doit être capable de recevoir un webhook plusieurs fois sans produire d'effets en double.
Les cas d'usage les plus courants
Les paiements en ligne. Stripe, PayPal et la plupart des passerelles de paiement utilisent des webhooks pour notifier les événements de paiement. Un webhook payment.succeeded déclenche la création de la commande, l'envoi de l'email de confirmation et la mise à jour du stock. Un webhook payment.failed déclenche une notification à l'équipe et éventuellement une relance du client. Ces webhooks sont indispensables parce que le paiement peut se confirmer ou échouer après que l'utilisateur a quitté la page de checkout.
Les formulaires web. Webflow envoie des webhooks à chaque soumission de formulaire. Plutôt que de surveiller manuellement les soumissions, un webhook notifie instantanément un outil tiers (CRM, outil d'email marketing, Slack) dès qu'un formulaire est rempli. C'est la base de la plupart des intégrations entre Webflow et les outils marketing.
Les déploiements et CI/CD. GitHub envoie des webhooks à chaque push de code, chaque pull request, chaque création de tag. Ces webhooks déclenchent automatiquement les pipelines de CI/CD : lancer les tests, construire l'application, déployer sur le serveur. C'est le mécanisme qui rend le déploiement continu possible.
Les e-commerces. Shopify envoie des webhooks pour les événements clés de la boutique : nouvelle commande, commande expédiée, produit mis à jour, client créé. Ces webhooks permettent de synchroniser la boutique avec des systèmes tiers comme un ERP, un outil de comptabilité ou un logiciel de gestion logistique.
Les outils de collaboration. Slack, Notion, Trello et de nombreux outils de productivité supportent les webhooks entrants pour afficher des notifications dans des canaux dédiés. Un webhook peut envoyer une notification dans un canal Slack dès qu'un nouveau lead est créé dans le CRM, qu'une commande est passée ou qu'un incident est détecté sur le serveur.
Webhook vs API : choisir le bon outil
Webhooks et API sont complémentaires mais ne s'utilisent pas dans les mêmes situations.
L'API (polling) est préférable quand : on a besoin de déclencher une action à la demande, quand on veut interroger l'état actuel d'une ressource (récupérer le détail d'une commande, lister les produits d'un catalogue), ou quand le système source ne supporte pas les webhooks.
Le webhook est préférable quand : on veut être notifié immédiatement d'un événement sans interroger régulièrement le service, quand les événements sont peu fréquents et imprévisibles (un paiement, une nouvelle commande, un formulaire soumis), ou quand le polling consommerait inutilement des ressources et des quotas d'API.
Dans les architectures modernes, les deux coexistent souvent : des webhooks pour les notifications d'événements en temps réel, des appels API pour les requêtes à la demande.
FAQ
Un webhook peut-il échouer ?
Oui. Si le endpoint récepteur est indisponible (serveur en maintenance, erreur 500), le webhook n'est pas traité. Les services sérieux comme Stripe implémentent des mécanismes de retry : ils renvoient le webhook plusieurs fois avec des délais croissants si le premier envoi n'a pas reçu de réponse 200. La surveillance des webhooks échoués dans les tableaux de bord des services émetteurs est une bonne pratique.
Faut-il savoir coder pour utiliser des webhooks ?
Pour les cas simples, non. Des outils comme Make ou n8n permettent de recevoir des webhooks et de déclencher des actions dans d'autres outils via des interfaces visuelles, sans écrire de code. Pour des intégrations plus complexes avec une logique de traitement spécifique, du développement est nécessaire.
Comment tester un webhook en développement local ?
En développement, l'URL du endpoint est localhost, qui n'est pas accessible depuis internet. Des outils comme ngrok ou Cloudflare Tunnel permettent d'exposer temporairement un port local avec une URL publique pour recevoir des webhooks pendant le développement. Des services comme Stripe proposent également une CLI qui permet de rediriger les webhooks vers un endpoint local sans exposer son ordinateur.
Quelle est la différence entre un webhook et un websocket ?
Un webhook est une notification HTTP ponctuelle envoyée d'un serveur vers un autre quand un événement se produit. Un websocket est une connexion bidirectionnelle persistante entre un navigateur et un serveur qui permet l'échange de messages en temps réel dans les deux sens. Un webhook est adapté pour des notifications d'événements. Un websocket est adapté pour des interfaces en temps réel comme les chats ou les tableaux de bord en direct.
