Comprendre les webhooks · Publié le · Emmanuel Sauvage
Qu’est-ce qu’un webhook ? Définition, fonctionnement et exemples
Formulaire de contact, paiement Stripe, nouvelle commande, commit GitHub… La plupart des outils web savent prévenir une autre application lorsqu’un événement se produit. Le mécanisme qui rend cela possible s’appelle un webhook. Voici une définition simple, son fonctionnement, des exemples et les bonnes pratiques à connaître.
Définition : un webhook, c’est quoi ?
Un webhook est une requête HTTP envoyée automatiquement par une application vers une URL que vous avez configurée, au moment précis où un événement survient. La requête contient les données de l’événement, généralement au format JSON ou sous forme de champs de formulaire.
Autrement dit : au lieu de demander régulièrement « y a-t-il du nouveau ? », vous donnez une adresse à l’application et c’est elle qui vous appelle quand il y a du nouveau.
Webhook vs API : la différence
- API (pull) : votre code interroge le service quand il en a besoin. Pour détecter un changement, il faut interroger régulièrement (polling), ce qui consomme des ressources et introduit un délai.
- Webhook (push) : le service envoie l’information dès que l’événement se produit. C’est plus réactif et plus économe.
Les deux sont complémentaires : beaucoup d’intégrations reçoivent un webhook puis appellent une API pour agir.
Comment fonctionne un webhook, étape par étape
- Vous fournissez une URL (l’« endpoint ») à l’application émettrice.
- Un événement se produit : formulaire envoyé, paiement validé, ticket créé…
- L’application envoie une requête HTTP, le plus souvent en
POST, vers votre URL avec les données. - Votre endpoint traite la requête : enregistrement, e-mail, notification, appel d’une autre API…
- Il répond rapidement avec un code HTTP 2xx pour confirmer la réception. Beaucoup d’émetteurs retentent l’envoi en cas d’erreur ou de délai dépassé.
POST /webhook/form/VOTRE_JETON HTTP/1.1
Host: webhooky.builders
Content-Type: application/json
{
"event": "contact.submitted",
"name": "Jean Dupont",
"email": "jean.dupont@example.com",
"message": "Bonjour, je souhaite un devis."
}Exemples concrets d’utilisation
- Formulaire de contact : à chaque envoi, un e-mail de confirmation part au visiteur et une alerte arrive sur Slack.
- Paiement : les prestataires de paiement envoient un webhook quand un paiement réussit ou échoue, pour activer un abonnement.
- Développement : les forges Git notifient votre CI à chaque push.
- Support : un nouveau ticket déclenche un SMS à la personne d’astreinte.
- SaaS : votre produit publie ses événements (inscription, résiliation) vers vos outils internes.
Recevoir un webhook : coder soi-même ou utiliser un service ?
Pour recevoir un webhook, il faut une URL publique en HTTPS capable de traiter la requête. Deux options :
- Développer l’endpoint dans votre application (contrôleur Symfony, route Express…). Vous maîtrisez tout, mais vous devez aussi gérer la sécurité, les erreurs, la journalisation et la maintenance de chaque intégration.
- Utiliser un service de webhooks comme Webhooky : vous obtenez une URL, puis vous configurez les actions à exécuter (e-mail Mailjet, Slack, SMS, appel HTTP…) et consultez l’historique des exécutions.
Bonnes pratiques de sécurité
- HTTPS uniquement pour protéger les données en transit.
- URL secrète : un jeton long et aléatoire dans l’URL, jamais publié dans un dépôt public.
- Signature : quand l’émetteur signe ses requêtes (en-tête HMAC par exemple), vérifiez-la.
- Validation des données reçues : ne faites jamais confiance au contenu brut.
- Idempotence : un même webhook peut arriver deux fois ; votre traitement doit le supporter.
- Réponse rapide : accusez réception tout de suite et traitez en arrière-plan si c’est long.
- Journalisation : gardez une trace de chaque réception et de chaque action pour diagnostiquer.
Questions fréquentes
Qu’est-ce qu’un webhook en une phrase ?
Un webhook est un appel HTTP automatique qu’une application envoie vers une URL que vous lui avez fournie, au moment où un événement se produit.
Quelle différence entre un webhook et une API ?
Avec une API, c’est vous qui interrogez le service quand vous en avez besoin. Avec un webhook, c’est le service qui vous prévient dès qu’un événement survient. On parle souvent d’« API inversée » ou de modèle push.
Faut-il savoir coder pour utiliser un webhook ?
Pour recevoir un webhook, il faut une URL capable de traiter la requête : soit un script que vous développez, soit un service qui le fait pour vous, comme Webhooky.
Un webhook est-il sécurisé ?
Il peut l’être : HTTPS obligatoire, URL non devinable gardée secrète, vérification de signature quand l’émetteur en fournit une, validation des données et limitation du débit.