À propos des webhooks

À propos des webhooks

Les webhooks vous permettent de vous abonner aux événements se produisant dans un système logiciel et de recevoir automatiquement une livraison de données sur votre serveur chaque fois que ces événements se produisent.

Les webhooks vous permettent de recevoir des données telles qu’elles se produisent, plutôt que d’interroger une API (appeler une API par intermittence) pour vérifier si les données sont disponibles. Vous n’avez besoin alors d’exprimer votre intérêt pour un événement qu’une seule fois, lorsque vous créez le webhook.

Les webhooks sont utilisés dans un large éventail de scénarios, notamment :

• Déclenchement de pipelines CI (intégration continue) sur un serveur CI externe. Par exemple, pour déclencher l’intégration continue dans Jenkins ou CircleCI lorsque le code est envoyé à une branche.
• Envoi de notifications sur les événements sur GitHub à des plateformes de collaboration. Par exemple, l’envoi d’une notification sur Discord ou Slack s’il existe une révision sur une demande de tirage (pull request).
• Mise à jour d’un suivi de problèmes externes comme Jira.
• Déploiement sur un serveur de production.
• Journalisation des événements à mesure qu’ils se produisent sur GitHub, à des fins d’audit.

À propos des webhooks sur GitHub

Lorsque vous créez un webhook, vous spécifiez une URL et vous abonnez à des événements qui se produisent sur GitHub. Lorsqu’un événement auquel votre webhook est abonné se produit, GitHub envoie une requête HTTP avec des données sur l’événement à l’URL que vous avez spécifiée. Si votre serveur est configuré pour repérer les livraisons de webhook à cette URL, il peut prendre des mesures lorsqu’il en reçoit une.

Par exemple, vous pouvez abonner vos webhooks aux événements qui se produisent lorsque le code est envoyé (push) à un référentiel, qu’une demande de tirage (pull request) est ouverte, qu’un site GitHub Pages est généré ou qu’un nouveau membre est ajouté à une équipe. Votre serveur peut répondre en déployant du code en production, en déclenchant un pipeline CI, en envoyant une notification ou en créant un projet GitHub pour le nouveau membre de l’équipe.

Vous devez créer un webhook dans un référentiel ou une organisation spécifique, GitHub Enterprise, ou GitHub App. Le webhook peut uniquement accéder aux ressources disponibles dans le référentiel, l’organisation, GitHub Enterprise, ou GitHub App où il est installé. Pour plus d’informations, consultez « Types de webhook ».

Pour plus d’informations sur la création des webhooks, consultez « Création de webhooks ». Pour plus d’informations sur les types d’événements auxquels vous pouvez vous abonner, consultez « Événements et charges utiles du webhook ». Pour plus d’informations sur la configuration de votre serveur pour effectuer une action en réponse à une livraison de charge utile, consultez « Gestion des livraisons de webhooks ».

Choix des webhooks ou de l’API REST

L’utilisation des webhooks présente les avantages suivants par rapport à l’utilisation de l’API :

• Les webhooks nécessitent moins d’efforts et ressources que l’interrogation d’une API.
• Les webhooks sont plus efficaces que les appels d’API. Si vous devez surveiller de nombreuses ressources, l’appel de l’API pour chaque ressource peut vous amener à atteindre rapidement votre quota de limites de débit d’API. Au lieu de cela, vous pouvez vous abonner à plusieurs événements webhook et recevoir des informations uniquement lorsqu’un événement se produit.
• Les webhooks autorisent des mises à jour en quasi temps réel, car les webhooks sont déclenchés lorsqu’un événement se produit.

Si vous n’avez besoin d’informations qu’une seule fois ou par intermittence, ou que vous souhaitez obtenir des informations à partir d’un petit ensemble de ressources sans envisager de mise à l’échelle, vous pouvez appeler l’API lorsque vous avez besoin des informations pertinentes.

Pour plus d’informations sur les meilleures pratiques à suivre lors de l’utilisation de webhooks, consultez « Meilleures pratiques en matière d’utilisation des webhooks ».

Pour aller plus loin

• « Types de webhook »