À propos des webhooks

À propos des webhooks

Les webhooks sont une méthode de communication qui permet aux utilisateurs de s’abonner à des événements se produisant dans un système logiciel. Les webhooks peuvent être déclenchés chaque fois que des événements spécifiques se produisent sur GitHub. Par exemple, vous pouvez configurer un webhook qui se déclenche quand :

• Du code est poussé vers un dépôt
• Une demande de tirage est ouverte
• Un site GitHub Pages est créé
• Un nouveau membre est ajouté à une équipe

Vous pouvez créer des webhooks pour une organisation, un référentiel ou un GitHub App. Vous pouvez également créer des webhooks pour vous abonner à des événements liés à GitHub Sponsors et GitHub Marketplace.

Vous pouvez créer jusqu’à 20 webhooks pour chaque événement sur chaque cible d’installation (organisation spécifique ou référentiel spécifique).

Pour plus d’informations sur la création des webhooks, consultez « Création de webhooks ».

À propos des événements webhook

Lors de la configuration d’un webhook, vous pouvez choisir les événements qui vous envoient des charges utiles. Pour limiter le nombre de requêtes HTTP sur votre serveur, vous devez vous abonner uniquement aux événements spécifiques que vous prévoyez de gérer. Pour obtenir la liste complète des événements webhook disponibles et leurs charges utiles, consultez « Événements et charges utiles du webhook ».

Certains événements webhook ont des actions, qui sont des opérations pouvant être effectuées sur la ressource que l’événement webhook représente. Si un événement webhook a plusieurs types d’actions, chaque action déclenchera une livraison de charge utile. Par exemple, l’événement webhook package déclenchera une livraison de charge utile lorsqu’un package est updated ou edited. Vous ne pouvez pas vous abonner à des actions webhook individuelles. Lorsque vous configurez un webhook, vous recevrez des charges utiles pour toutes les actions liées à ce webhook.

Par défaut, les webhooks installés sur une organisation ou un référentiel sont uniquement abonnés à l’événement push. Par défaut, les webhooks sur GitHub Apps ne sont abonnés à aucun événement. Vous pouvez modifier les événements auxquels un webhook est abonné à tout moment.

À propos des livraisons de webhooks

Lorsque vous recevez une livraison de webhook, la charge utile contiendra le nom de l’événement et de l’action qui a déclenché la livraison, ainsi que d’autres informations sur l’événement lui-même. Pour plus d’informations sur les en-têtes de livraison inclus dans chaque charge utile et un exemple de livraison, consultez « Événements et charges utiles du webhook ». Certaines informations sont incluses dans la plupart ou dans toutes les livraisons de webhook, telles que l’utilisateur qui a effectué l’événement, ou l’organisation ou le référentiel où l’événement s’est produit.

Lorsque vous créez un webhook, vous spécifiez une URL où vous souhaitez recevoir les événements de webhook. GitHub envoie une charge utile HTTP POST à cette URL lorsque des événements auxquels le webhook est abonné se produisent. Votre serveur peut ensuite traiter et répondre au webhook. Pour plus d’informations, consultez « Gestion des livraisons de webhooks ».

Pour plus d’informations sur l’affichage des livraisons de webhook, consultez « Affichage des livraisons de webhook ».

Quand utiliser des webhooks

Les webhooks peuvent être 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.

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

Les webhooks présentent les avantages suivants sur 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 projet d’extension, 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 ».

À propos des autorisations pour la gestion des webhooks

Pour gérer les webhooks, vous devez posséder ou disposer d’un accès administrateur à la ressource sur laquelle le webhook est créé et repère des événements. Par exemple, pour gérer les webhooks de l’organisation, vous avez besoin d’autorisations d’administrateur pour cette organisation. Pour en savoir plus sur la création des différents types de webhooks, consultez « Création de webhooks ».

Remplacement des anciens services GitHub par des webhooks

Les services GitHub (parfois appelé « Service Hooks ») constituent l’ancienne méthode d’intégration selon laquelle GitHub hébergeait une partie des services de notre intégrateur via le référentiel github-services. En 2019, nous avons déconseillé les services GitHub en faveur de l’intégration des webhooks. Pour plus d’informations sur cette dépréciation, consultez l’article.