Programmation · concepts · web

Qu’est-ce qu’un webhook ?

Vous configurez un paiement, et votre application réagit à l’instant où l’argent est encaissé. Vous poussez un commit, et un build démarre tout seul. Derrière cette immédiateté, il y a presque toujours un webhook. Ce guide explique, simplement, ce qu’est un webhook, en quoi il diffère d’un appel d’API classique, comment le recevoir en sécurité, et où vous en dépendez déjà.

La définition courte

Un webhook est une requête HTTP automatique qu’un service envoie à une URL que vous contrôlez quand un événement se produit. Plutôt que de demander des nouvelles à un service, c’est lui qui vous prévient dès qu’il y en a.

D’où le surnom d’« API inversée ». Avec une API classique, vous êtes le client : vous faites la requête, le serveur répond. Avec un webhook les rôles s’inversent — le fournisseur devient le client et votre endpoint est le serveur qu’il appelle.

Webhook vs polling d’une API

Avant les webhooks, la façon habituelle de rester à jour était le polling : appeler une API sur une minuterie (« du nouveau ? ») encore et encore. C’est simple mais gaspilleur — la plupart des appels ne renvoient rien, et il y a toujours un décalage entre l’événement et la vérification suivante.

• Polling — vous demandez en boucle. Beaucoup de requêtes inutiles, réaction retardée, simple à construire.
• Webhook — le service vous prévient une fois, immédiatement. Efficace et quasi temps réel, mais vous devez faire tourner un endpoint pour le recevoir.

Comment ça marche, étape par étape

1. Vous enregistrez une URL (votre endpoint) auprès du fournisseur et choisissez les événements qui vous intéressent.
2. Quand un tel événement survient, le fournisseur envoie un POST HTTP à votre URL avec un corps (souvent du JSON) qui le décrit.
3. Votre serveur lit le contenu, renvoie vite un statut 2xx pour l’accuser, et fait le vrai travail ensuite.
4. Si votre endpoint est hors ligne ou renvoie une erreur, la plupart des fournisseurs ré-essaient avec backoff — d’où les doublons possibles.

Une livraison ressemble à n’importe quelle requête HTTP :

POST /webhooks/payments  HTTP/1.1
Host: votreapp.com
X-Signature: t=1718600000,v1=9f86d08...

{ "event": "payment.succeeded", "id": "pay_42", "amount": 1999 }

Des exemples que vous connaissez déjà

• Paiements — Stripe et PayPal envoient un webhook quand un paiement réussit, échoue ou est remboursé, pour que votre app mette à jour la commande sans polling.
• Hébergement de code — GitHub et GitLab déclenchent un webhook sur push, pull request ou issue : c’est ainsi que builds CI et bots sont lancés.
• Messagerie — Slack, Discord et les plateformes de chat utilisent des webhooks entrants pour poster des messages et notifier votre app.

Le recevoir en sécurité

Un récepteur robuste fait quatre choses :

• Servir en HTTPS et accepter les POST ; répondre vite par un 2xx, puis traiter en asynchrone.
• Vérifier la signature — les fournisseurs signent le corps (un HMAC avec un secret partagé). Rejeter ce qui échoue.
• Être idempotent — le même événement peut arriver plusieurs fois ; utilisez l’id de l’événement pour que la re-livraison soit sans effet.
• Renvoyer les erreurs honnêtement — si vous ne pouvez pas traiter, renvoyez un non-2xx pour que le fournisseur ré-essaie au lieu d’abandonner.

Les webhooks ont besoin d’un endpoint toujours en ligne avec une URL HTTPS publique — c’est pourquoi un petit serveur ou une instance cloud est le foyer habituel d’un récepteur de webhooks, plutôt qu’une machine qui s’endort.

Questions fréquentes

Qu’est-ce qu’un webhook, simplement ?

Un webhook est un message automatique qu’un service envoie à une URL que vous contrôlez à l’instant où quelque chose se produit — par exemple « un paiement a réussi » ou « un commit a été poussé ». Au lieu de demander sans cesse au service « du nouveau ? » (le polling de son API), le service vous appelle par une requête HTTP POST dès que l’événement survient. On parle souvent d’« API inversée » : avec une API classique c’est vous qui faites la requête ; avec un webhook c’est le service qui vous la fait.

Quelle différence entre un webhook et une API ?

Ils sont liés mais vont en sens inverse. Avec une API (REST) classique, vous envoyez une requête au fournisseur quand vous voulez des données, et il répond. Avec un webhook, le fournisseur envoie une requête à votre serveur quand un événement se produit : les données vous sont poussées en quasi temps réel sans rien demander. Un webhook passe par la même mécanique HTTP qu’une API — c’est le fournisseur qui joue le rôle de client et votre endpoint celui de serveur.

Pourquoi un webhook plutôt que du polling ?

Le polling consiste à appeler une API à intervalle régulier pour vérifier les changements, ce qui gaspille des requêtes et ajoute un délai entre l’événement et votre réaction. Les webhooks vous poussent l’événement à l’instant où il arrive : plus efficaces et bien plus proches du temps réel. En contrepartie, vous devez faire tourner un endpoint toujours en ligne, et gérer les ré-essais et les livraisons en double.

Comment recevoir un webhook en sécurité ?

Exposez un endpoint HTTPS qui accepte les POST, renvoyez vite un statut 2xx pour accuser réception, puis traitez le travail de façon asynchrone. Vérifiez la signature que le fournisseur envoie (un HMAC du corps avec un secret partagé) pour confirmer l’authenticité, et rendez le traitement idempotent car un même événement peut être livré plusieurs fois. Rejetez tout ce qui échoue à la vérification de signature.

En résumé

Un webhook, c’est la façon du web de dire « ne nous appelez pas, on vous appellera » : une requête HTTP automatique qu’un service envoie à votre endpoint dès qu’un événement se produit. C’est plus efficace et bien plus temps réel que le polling d’une API — au prix d’un endpoint fiable, qui vérifie les signatures, pour le recevoir. Une fois repérés, vous verrez les webhooks derrière presque chaque « ça s’est mis à jour tout seul » du logiciel moderne.