Qu'est-ce qu'un Webhook ?

Qu'est-ce qu'un webhook ?

Un webhook est une requête HTTP POST qu'un service envoie automatiquement à un autre service quand quelque chose se passe. Le service receveur enregistre une URL auprès du service émetteur à l'avance ; quand l'événement déclencheur survient, l'émetteur POST un payload JSON (ou form-encoded) à cette URL. Le receveur retourne un 200 OK pour confirmer, et l'émetteur passe à autre chose. Pas de polling, pas d'attente — événements livrés au moment où ils surviennent.

Les webhooks sont la plomberie des intégrations internet modernes. Quand Stripe charge une carte, il POST un événement charge.succeeded à votre URL webhook enregistrée. Quand GitHub merge une PR, il POST un événement pull_request.closed. Quand Shopify expédie une commande, votre app reçoit un POST order.fulfilled. Le pattern est identique sur des milliers de produits SaaS : je vous dis une URL, vous me POSTez quand des choses se passent.

Webhooks vs polling : pourquoi les webhooks ont gagné

Avant les webhooks, l'intégration signifiait polling : votre service demande à l'API à plusieurs reprises "y a-t-il du nouveau ?" toutes les quelques secondes. Le polling a trois problèmes :

• Latence. Si vous pollez toutes les 60 s, votre lag moyen de détection d'événement est 30 s. Les features temps réel (chat, paiements, alertes) ne tolèrent pas ça.
• Charge gaspillée. 99% des polls retournent "rien de nouveau". Vous martelez l'API pour des réponses vides, payant compute et bande passante pour rien.
• Limites de débit. La plupart des APIs plafonnent les requêtes par minute. Le polling agressif fait sauter le budget ; le polling conservateur empire la latence.

Les webhooks inversent le modèle. Le fournisseur sait quand un événement se passe (il l'a causé), donc il vous POST immédiatement — typiquement en quelques centaines de millisecondes. Zéro polling, zéro requêtes gaspillées, zéro gaspillage de limite de débit. Le fournisseur obtient une logique d'intégration plus simple ; le consommateur obtient des mises à jour quasi temps réel.

Comment fonctionne une livraison webhook (étape par étape)

Un cycle de vie webhook typique :

1. Vous enregistrez une URL auprès du fournisseur. Habituellement dans une UI de paramètres : "Envoyer les webhooks à https://api.myapp.com/webhooks/stripe". Le fournisseur stocke cette URL.
2. Un événement se produit côté fournisseur. Un utilisateur paie, un build se termine, une ligne est mise à jour.
3. Le fournisseur construit un payload. Habituellement JSON : {"event": "charge.succeeded", "data": {"id": "ch_123", "amount": 1500}}.
4. Le fournisseur POST le payload à votre URL. Les en-têtes incluent habituellement le type d'événement, un ID de livraison pour l'idempotence et un en-tête de signature pour la vérification.
5. Votre endpoint reçoit le POST et le traite. Vérifier la signature, parser le JSON, faire ce que l'événement requiert (mettre à jour la BDD, envoyer un email, fan-out vers d'autres services).
6. Votre endpoint retourne 200 OK rapidement. La plupart des fournisseurs considèrent les réponses non-2xx comme un échec de livraison et réessayent avec backoff exponentiel. Si le traitement prend plus de quelques secondes, accepter le webhook (200) et mettre le travail en file pour traitement asynchrone.

Vérifier l'authenticité du webhook (ne sautez pas ça)

Quiconque connaît votre URL webhook peut y POSTer. Sans vérification, un attaquant peut falsifier des événements — prétendre que Stripe vous a payé, prétendre que GitHub a mergé une PR malveillante, prétendre qu'une expédition est arrivée. Trois patterns courants de vérification :

• Signature HMAC. Le fournisseur signe le payload avec un secret partagé en utilisant HMAC-SHA256, envoie la signature dans un en-tête (Stripe-Signature, X-Hub-Signature-256, etc.). Votre endpoint recalcule le HMAC et rejette les requêtes qui ne correspondent pas. La plupart des fournisseurs modernes (Stripe, GitHub, Shopify) utilisent ça.
• Token bearer dans l'en-tête. Plus simple mais moins robuste : le fournisseur envoie un token secret statique dans Authorization: Bearer .... Quiconque capture une requête valide peut la rejouer ; moins courant dans les systèmes modernes.
• Liste blanche d'IP. N'accepter les POSTs que depuis les plages d'IP fournisseur documentées. Utile en défense en profondeur mais casse quand les fournisseurs font tourner les IPs.

La signature HMAC est le default correct. Combinez avec une fenêtre de replay courte (rejeter les requêtes avec timestamps plus anciens que quelques minutes) pour prévenir les attaques de replay.

Idempotence : gérer les livraisons dupliquées

Les réseaux échouent. Les fournisseurs réessayent. Votre endpoint recevra le même webhook deux fois — parfois plus. Les intégrations naïves créent des lignes de base de données dupliquées, envoient des emails dupliqués, facturent les clients deux fois. L'idempotence prévient ça.

Deux approches courantes :

• Clé d'idempotence du fournisseur. La plupart des fournisseurs incluent un ID de livraison dans les en-têtes (Stripe-Webhook-Id, X-GitHub-Delivery) — globalement unique par événement. Stocker l'ID après traitement et rejeter les doublons. Simple, fiable.
• Dedup au niveau application. Calculez un hash du type d'événement + champs clés (ex. ID de commande + statut) et traitez les hashs répétés dans un TTL comme des doublons. Utile quand l'ID de livraison du fournisseur n'est pas fiable.

Patterns de fiabilité webhook

Confirmer vite, traiter async

Le receveur de webhook devrait retourner 200 en moins de 1-2 secondes, même si le travail réel prend plus longtemps. Poussez le payload sur une queue (SQS, Redis stream, Postgres LISTEN/NOTIFY) et traitez depuis un worker. Le traitement synchrone lent cause des timeouts fournisseur, des retries et des livraisons dupliquées.

Implémentez une table outbox / inbox

Persistez les webhooks entrants dans une table inbox AVANT de faire tout traitement. Si votre worker crashe en plein traitement, vous pouvez rejouer depuis l'inbox. L'ID de livraison du fournisseur devient la clé primaire de l'inbox pour l'idempotence.

Monitorez le succès de livraison

La plupart des fournisseurs exposent un log de livraison (Stripe → Webhooks → livraisons récentes). Vérifiez-le périodiquement. Un pic de réponses 5xx ou 4xx sur votre endpoint signifie habituellement que votre inbox est cassée avant que vous ne le remarqueriez autrement.

Utilisez des tunnels webhook en développement

Des outils comme ngrok, Smee et Cloudflare Tunnel exposent votre localhost à l'internet public pour que les fournisseurs puissent POSTer à votre environnement de dev. Essentiel pour le débogage local — les webhooks ne peuvent pas atteindre localhost:3000 depuis les serveurs de Stripe sans un.

Gotchas webhook courants

• Livraison dans le désordre. Les fournisseurs livrent généralement les événements dans l'ordre, mais les retries réseau peuvent inverser l'ordre. N'assumez pas que order.created arrive avant order.fulfilled — gérez les deux possibilités.
• Limites de taille de payload. Beaucoup de fournisseurs plafonnent les payloads à 4-8 Mo. Les grandes entités (ex. un export de 50 000 lignes) sont expédiées comme URL à récupérer séparément, pas inline.
• Stricteté HTTP/HTTPS. La plupart des fournisseurs requièrent HTTPS ; certains rejettent les certs auto-signés. Utilisez un vrai cert (Let's Encrypt est gratuit).
• Parsing du body avant vérification de signature. Beaucoup de schémas HMAC signent le body brut. Si votre framework parse JSON d'abord, vous n'avez peut-être plus les bytes bruts. Utilisez un middleware qui préserve le body brut pour la vérification, puis parse.

FAQ : Webhooks

Les webhooks sont-ils la même chose qu'une URL de callback ?

Oui — "webhook", "callback HTTP" et "API inverse" décrivent tous le même pattern. Différents termes venant de différentes communautés (développeurs web, fournisseurs d'API, défenseurs REST) mais le mécanisme technique est identique.

Quelle est la différence entre webhooks et WebSockets ?

Les webhooks sont des POST HTTP unidirectionnels envoyés quand des événements se produisent. Les WebSockets sont des connexions TCP bidirectionnelles persistantes. Utilisez les webhooks pour des événements occasionnels entre services ; utilisez WebSockets pour la communication bidirectionnelle haute fréquence (chat, curseurs en direct, collaboration temps réel).

Mon receveur peut-il être hébergé sur serverless ?

Oui — les webhooks vont très bien avec AWS Lambda, Cloudflare Workers ou Vercel functions. Le modèle d'accusé de réception bref (retourner 200 vite, traiter async) mappe bien à serverless. Dimensionnez juste la fonction pour des cold starts rapides ; certains fournisseurs timeoutent agressivement.

Comment tester les handlers webhook localement ?

Utilisez un tunnel : ngrok, Smee, Cloudflare Tunnel. Le tunnel expose votre localhost via une URL HTTPS publique à laquelle les fournisseurs peuvent POSTer. Stripe, GitHub et la plupart des fournisseurs modernes offrent aussi un CLI pour forwarder les événements directement à localhost sans tunnel.

Que se passe-t-il si mon endpoint est down quand un événement survient ?

La plupart des fournisseurs réessayent avec backoff exponentiel (1 min, 5 min, 30 min, etc.) pendant 24-72 heures. Après ça, l'événement est abandonné — et vos données sont définitivement incohérentes. Monitorez les échecs de livraison et ayez un mécanisme de replay idempotent pour les pannes plus longues que la fenêtre de retry.

Devrais-je utiliser webhooks ou polling pour mon use case ?

Webhooks pour : événements temps réel, triggers basse fréquence, notifications de paiement, tout où la latence compte. Polling pour : sync de données en masse, situations où le fournisseur n'offre pas de webhooks, ou quand vous ne pouvez pas exécuter un endpoint HTTPS public. En pratique, les intégrations modernes utilisent les deux : webhooks pour alertes immédiates, polling périodique comme filet de sécurité pour attraper les livraisons manquées.

Comment LoadFocus utilise les webhooks

LoadFocus expose des webhooks pour les événements de fin de test et d'alerte : quand votre test de charge planifié se termine, nous POSTons l'URL des résultats à votre endpoint enregistré pour que votre pipeline CI puisse réagir (poster sur Slack, gater un déploiement, mettre à jour un tableau de bord). Quand un moniteur d'API déclenche une alerte, le même pattern de payload livre l'incident à PagerDuty, Opsgenie ou votre service personnalisé. Configurez les webhooks dans vos paramètres de compte ; les signatures HMAC sont incluses par défaut.