Webhook : Comprendre, configurer et sécuriser les notifications automatiques entre applications

Webhook est un mécanisme qui permet à un système d'informer automatiquement un autre système lorsqu'un événement précis se produit. Au lieu d'effectuer des requêtes constantes vers un serveur, l'application reçoit les données exactement au moment où elles apparaissent : par exemple, après un paiement réussi, une nouvelle commande ou un changement de statut de livraison.

Les webhooks sont particulièrement utiles lors de l'intégration de plusieurs services. Ils réduisent le nombre de requêtes inutiles et permettent de réagir plus rapidement aux changements. Bien que le webhook soit étroitement lié à une API classique, il fonctionne selon un principe différent.

Qu'est-ce qu'un webhook et à quoi servent-ils ?

Définition simple du webhook

Pour bien comprendre la différence entre une API et un webhook, prenons l'exemple des notifications.

Avec une API classique, l'application interroge régulièrement un autre serveur pour savoir : " Des nouvelles données sont-elles disponibles ? ". Si rien n'a changé, elle répète cette requête à intervalles réguliers.

Le webhook fonctionne de manière opposée. L'application communique à l'avance une adresse spécifique au service, et ce dernier envoie une requête à cette adresse dès qu'un événement pertinent se produit.

Par exemple, un site e-commerce n'a plus besoin de vérifier toutes les quelques secondes auprès du système de paiement si le client a réglé sa commande. Le prestataire de paiement peut envoyer de lui-même un webhook dès que le paiement est confirmé.

Voilà pourquoi les webhooks sont souvent considérés comme des mécanismes de notification entre applications. Un système ne demande pas continuellement l'état d'un autre, il attend simplement les messages sur les événements importants.

Quels problèmes les webhooks résolvent-ils ?

Le webhook s'utilise partout où il est essentiel de réagir rapidement à un changement provenant d'un autre service. Exemples classiques :

• Un système de paiement informe la boutique d'un paiement réussi ;
• Un CRM reçoit une nouvelle demande depuis le site web ;
• Un service de livraison envoie un nouveau statut de commande ;
• Une plateforme Git déclenche une compilation après l'ajout de nouveau code ;
• Un messager transmet un nouveau message à un bot ;
• Un service cloud notifie la fin du traitement d'un fichier.

La particularité de ces scénarios est que l'action est déclenchée par un événement. Le système ne vérifie pas l'état à intervalles réguliers, il reçoit un signal uniquement lorsque quelque chose s'est véritablement passé.

Ce principe s'applique non seulement aux intégrations spécifiques, mais aussi aux architectures logicielles plus larges. Pour en savoir plus, consultez l'article Pourquoi l'architecture event-driven rend les systèmes plus rapides et réactifs.

Grâce à cela, le webhook est particulièrement adapté à l'automatisation. Après réception d'un événement, le programme peut modifier le statut d'une commande, envoyer une notification à l'utilisateur, enregistrer des données ou lancer un autre processus.

Comment fonctionne un webhook ?

Événement, URL et requête HTTP

Pour qu'un webhook fonctionne, le système destinataire doit d'abord créer une URL spécifique : un endpoint. C'est à cette adresse que l'autre service enverra les notifications d'événements.

Le schéma est simple :

• Un événement se produit ;
• Le service génère les données ;
• Il envoie une requête HTTP ;
• Le système destinataire la traite.

Par exemple, un utilisateur paie une commande. Le prestataire de paiement valide la transaction et envoie une requête HTTP au webhook du site marchand. Une fois la requête reçue, le site marque la commande comme " Payée " et peut lancer les étapes suivantes automatiquement.

La méthode HTTP la plus courante pour les webhooks est POST, car il faut transmettre des informations sur l'événement. Le format précis varie selon le service ; certaines plateformes utilisent d'autres méthodes HTTP.

Que contient la requête webhook ?

La requête webhook se compose généralement de plusieurs parties. L'URL correspond à l'adresse du gestionnaire, les en-têtes HTTP peuvent transporter des données techniques, et les informations principales sur l'événement se trouvent dans le corps de la requête.

Dans de nombreux services, les données sont transmises au format JSON. Par exemple, une notification de paiement peut contenir l'identifiant de la commande, le montant, la devise, le statut de paiement et la date de l'opération.

{
  "event": "payment.success",
  "order_id": "A1024",
  "status": "paid"
}

En recevant une telle requête, l'application lit le champ event, identifie le type d'événement et déclenche la logique adéquate. Si l'événement concerne un paiement, la commande passe à l'état " payée ". S'il s'agit d'une livraison, son statut est mis à jour.

Après traitement du webhook, le serveur retourne généralement un code HTTP. Un code dans la plage 200 indique que la requête a bien été reçue. Si le serveur répond par une erreur ou ne répond pas, le service expéditeur peut retenter la livraison de l'événement.

Exemple de fonctionnement d'un webhook

Imaginons une boutique en ligne connectée à un système de paiement externe.

Un client passe commande et accède à la page de paiement. Une fois le paiement effectué, le prestataire reçoit la confirmation de la banque. À ce stade, la boutique ne connaît pas encore le résultat de la transaction.

Plutôt que de vérifier en boucle l'état du paiement via l'API, le système de paiement envoie un webhook :

payment.success → webhook de la boutique → changement du statut de la commande

Le serveur de la boutique reçoit la notification, vérifie les données et passe la commande à " Payée ". Ensuite, la boutique peut envoyer un reçu, informer l'entrepôt et commencer la préparation de l'expédition.

Cette approche est particulièrement utile lorsque l'événement peut survenir quelques secondes, minutes ou même heures après la demande initiale. L'application n'a pas à contrôler l'état en continu : elle attend simplement le webhook.

Webhook et API : quelles différences ?

L'API fonctionne sur demande, le webhook sur événement

La différence majeure entre un webhook et une API classique réside dans l'initiateur de l'échange de données.

Avec une API, l'application envoie elle-même une requête au serveur : par exemple, pour obtenir la liste des commandes, le profil d'un utilisateur ou le statut d'un paiement. Le serveur ne répond que sur sollicitation.

Le webhook suit une logique inverse. Le destinataire fournit en amont son URL, et le service source envoie une requête à cette adresse dès qu'un événement pertinent survient.

On peut résumer ces deux modèles ainsi :

• API : " Demander si quelque chose s'est produit ";
• Webhook : " Recevoir une notification lorsqu'un événement se produit ".

Dans la documentation technique, on parle souvent de modèles pull (API) et push (webhook). L'API sert au modèle pull, où le client récupère les données, tandis que le webhook s'inscrit dans le modèle push, où les données sont envoyées automatiquement au destinataire.

Webhook vs REST API

Webhook et REST API utilisent les mêmes technologies internet de base : HTTP, URL, en-têtes, méthodes de requête et formats comme JSON. Toutefois, leurs usages diffèrent.

Par exemple, via l'API, une boutique peut demander des informations sur un paiement précis. Via webhook, c'est le prestataire de paiement qui informe la boutique qu'un paiement a été effectué avec succès.

Comparer webhook et API comme deux technologies totalement exclusives n'est donc pas tout à fait correct.

Le webhook ne remplace pas l'API

En pratique, webhook et API sont souvent utilisés conjointement.

L'API sert à obtenir ou modifier des données sur demande. Le webhook permet de recevoir rapidement une notification lorsqu'un événement survient.

Imaginons un CRM. Via l'API, l'application peut récupérer la fiche d'un client, modifier un numéro de téléphone ou consulter l'historique des commandes. Le webhook, lui, notifie un système externe lorsqu'un nouveau client est créé ou qu'une opportunité change d'étape.

Parfois, le webhook ne transmet qu'un minimum d'informations : par exemple, l'identifiant de l'objet et le type d'événement. L'application peut alors utiliser l'API pour aller chercher les données complètes.

Ce schéma permet d'éviter les requêtes répétitives tout en conservant la flexibilité de l'API classique.

Quand utiliser un webhook ou une API classique ?

Quand le webhook est-il préférable ?

Le webhook est idéal lorsque le système doit être informé d'un événement immédiatement après sa survenue.

Exemples typiques : confirmation de paiement, création d'une nouvelle commande, changement de statut de livraison, arrivée d'un nouveau lead dans le CRM, chargement d'un fichier ou publication de code dans un dépôt.

Dans ces cas, des requêtes régulières à l'API créent une forte charge inutile : interroger le serveur chaque minute pour savoir si le statut d'une commande a changé entraîne souvent des réponses identiques. Le webhook élimine cette nécessité : la requête n'est envoyée qu'après un changement réel.

Les webhooks sont donc particulièrement adaptés à l'automatisation et à l'intégration de services nécessitant une réaction quasi-instantanée aux événements.

Quand l'API classique reste-t-elle préférable ?

L'API reste le meilleur choix si l'application doit accéder aux données à tout moment, sur demande.

Par exemple, lorsqu'un utilisateur ouvre la page de son compte client et souhaite voir ses commandes, l'application interroge l'API pour obtenir la liste à jour.

L'API est également requise pour :

• effectuer des recherches ;
• récupérer des listes d'objets ;
• créer ou modifier des enregistrements ;
• supprimer des données ;
• demander des infos détaillées par identifiant ;
• choisir le moment d'interroger le serveur.

Le webhook n'est pas conçu pour ces usages. Il notifie d'un événement, mais ne permet généralement pas de demander des informations arbitraires à la demande.

En réalité, une approche combinée est fréquente : le webhook signale un changement, puis l'application utilise l'API pour récupérer les données nécessaires.

Webhook, polling et WebSocket

Le webhook n'est pas le seul moyen de recevoir des mises à jour d'un service tiers. Selon le besoin, on peut aussi utiliser le polling ou WebSocket.

Polling : il s'agit de requêtes régulières au serveur. Par exemple, une application demande toutes les dix secondes à l'API s'il y a de nouveaux messages. Cette méthode est simple à mettre en place, mais une multitude de requêtes constantes consomme des ressources même en l'absence de changement.

Le webhook ne crée pas de connexion permanente. Le service envoie une requête HTTP unique seulement lorsqu'un événement prédéfini survient. Cette approche est idéale pour les intégrations serveur, notifications et automatisations.

WebSocket permet d'établir une connexion bidirectionnelle persistante entre client et serveur. Les deux parties peuvent échanger des données à tout moment. C'est la solution privilégiée pour les chats, jeux en ligne, plateformes de trading et autres applications nécessitant un échange d'informations en temps réel.

Pour une explication détaillée du fonctionnement en connexion continue, consultez l'article WebSocket : le guide ultime pour des données en temps réel sur le web.

Le choix dépend de la nature des données : API si l'application décide quand demander l'information ; webhook pour réagir automatiquement à des événements ; WebSocket pour un flux bidirectionnel permanent en temps réel.

Comment configurer un webhook et quels sont les points importants ?

Création d'un endpoint webhook

Pour fonctionner, le destinataire du webhook doit disposer d'une URL publique accessible afin que le service externe puisse y envoyer ses requêtes HTTP. Cette adresse est appelée webhook endpoint.

Le développeur crée un gestionnaire qui reçoit, vérifie et traite les données entrantes. Cette URL est ensuite renseignée dans les paramètres du service source.

Exemple d'endpoint :

https://example.com/webhooks/payment

Lorsque l'événement cible se produit, le service envoie la requête à cette adresse.

Il est essentiel que l'endpoint soit accessible depuis Internet et qu'il prenne en charge HTTPS. Pour le développement local, on utilise souvent des tunnels ou services de test qui fournissent temporairement une adresse publique au poste du développeur.

Vérification de l'authenticité du webhook

Le endpoint webhook étant ouvert aux requêtes entrantes, il ne faut pas considérer chaque requête reçue comme fiable par défaut.

Si un attaquant découvre l'adresse du webhook, il peut tenter d'envoyer un faux événement. C'est pourquoi de nombreux services signent les requêtes webhook à l'aide d'une clé secrète.

Le système destinataire calcule la signature de la requête et la compare à celle transmise par le service. Si elles correspondent, on peut valider que les données proviennent bien de la source attendue et qu'elles n'ont pas été altérées.

Des tokens secrets, une vérification de la connexion HTTPS et des restrictions par adresses IP peuvent également renforcer la sécurité si le service le permet.

Relivraison et gestion des doublons

Un webhook ne garantit pas que la requête soit toujours traitée avec succès du premier coup. Le serveur peut être temporairement indisponible, la connexion interrompue ou le traitement trop long.

De nombreuses plateformes implémentent donc un mécanisme de relivraison (retry) : si l'endpoint retourne une erreur ou ne répond pas à temps, le service répète la requête plus tard.

Il arrive donc que le même événement soit envoyé plusieurs fois. L'application doit être capable de détecter les doublons et éviter d'effectuer deux fois la même opération.

Cela est crucial pour les paiements : si un webhook de paiement réussi arrive deux fois, le système ne doit pas créditer deux fois le compte, créer deux commandes ou expédier deux colis.

On utilise souvent un identifiant d'événement pour cela. Avant toute action, l'application vérifie si cet ID a déjà été traité, une pratique appelée traitement idempotent.

Logs et codes de réponse

Après réception du webhook, le serveur doit retourner un code HTTP. Un code 200 confirme le traitement réussi.

En cas d'erreur, le service source considérera la livraison comme un échec et réessaiera l'envoi.

Il n'est pas toujours recommandé d'effectuer tout le traitement lourd directement dans l'endpoint. Si l'opération prend du temps, il est préférable de vérifier rapidement l'événement, de l'ajouter à une file d'attente, de retourner une réponse positive, puis de traiter la suite en différé.

La journalisation est également importante : il faut enregistrer l'heure de réception, le type d'événement, son identifiant et le résultat du traitement. Cela aide à comprendre pourquoi une notification n'a pas été traitée ou pourquoi le service a réémis la requête.

Un webhook correctement configuré n'est pas qu'une simple URL acceptant des requêtes POST. Une intégration fiable doit tenir compte de la vérification de la source, la relivraison, la gestion des doublons, les erreurs et la possibilité d'indisponibilité temporaire du serveur.

Conclusion

Le webhook permet à un système d'informer automatiquement un autre système lorsqu'un événement spécifique se produit, sans recourir à des vérifications constantes via API. Il est particulièrement adapté aux paiements, notifications, intégrations entre services, automatisations et à tous les processus nécessitant une réaction rapide aux changements.

La différence essentielle entre le webhook et l'API classique réside dans la direction de l'interaction. Avec l'API, le client demande lui-même les données ; avec le webhook, le service source envoie une notification après un événement. Les webhooks ne remplacent pas l'API : dans la plupart des cas, les deux technologies fonctionnent ensemble.

Si le système doit obtenir des données à la demande, effectuer des recherches ou modifier des objets, l'API est adaptée. Pour réagir automatiquement à des événements précis, le webhook est idéal. Pour un échange bidirectionnel en temps réel, on privilégie généralement WebSocket.

Lors de l'intégration d'un webhook, il est crucial de prendre en compte la sécurité, la vérification de signature, la relivraison, la gestion des doublons et le traitement correct des erreurs. Ce sont ces détails qui transforment un simple endpoint webhook en une intégration fiable entre services.