Utilisation de webhooks avec des applications GitHub

À propos des webhooks et GitHub Apps

Les webhooks permettent à votre GitHub App de recevoir des notifications en temps réel lorsque des événements se produisent sur GitHub, par exemple quand quelqu’un envoie (push) une validation ou ouvre une demande de tirage (pull request) dans un référentiel auquel votre application peut accéder. Pour plus d’informations sur les webhooks, consultez À propos des webhooks. Pour obtenir un tutoriel qui montre comment utiliser des webhooks avec un GitHub App, consultez « Génération d’une application GitHub qui répond aux événements de webhook ».

Vous pouvez configurer votre GitHub App pour recevoir des webhooks pour des événements spécifiques sur GitHub et y prendre automatiquement des mesures. Pour plus d’informations sur les types de webhooks que vous pouvez recevoir, consultez « Événements et charges utiles du webhook ».

Pour recevoir des événements webhook dans votre GitHub App, vous devez activer les webhooks pour votre inscription d’GitHub App et spécifier une URL de webhook où GitHub enverra les charges utiles du webhook.

Si votre GitHub App n’a pas besoin de répondre aux webhooks ou ne sera utilisée que pour l’authentification, vous pouvez désactiver la fonction de webhook pour votre inscription d’GitHub App. Vous n’avez pas besoin de spécifier une URL de webhook.

Pour plus d’informations sur l’inscription d’une GitHub App, consultez « Inscription d’une application GitHub ». Pour plus d’informations sur la modification des webhooks auxquels une inscription d’GitHub App s’abonne, consultez Modification d’une inscription d’application GitHub.

Choix d’une URL de webhook

Lorsque vous activez des webhooks dans votre inscription d’GitHub App, vous devez spécifier une URL de webhook. L’URL du webhook est l’adresse d’un serveur web qui recevra les charges utiles d’événement webhook envoyées à votre GitHub App. Le serveur peut ensuite prendre des mesures en fonction du contenu de la charge utile. Vous devez choisir un serveur web approprié pour le volume de trafic de webhook que votre GitHub App rencontrera.

Choix d’une URL de webhook pour le développement et le test

Pendant que vous développez et testez votre application, vous pouvez utiliser un service de livraison de charge utile webhook comme Smee pour capturer et transférer des charges utiles webhook vers votre environnement de développement local. N’utilisez jamais Smee pour une application en production, car les canaux Smee ne sont pas authentifiés ni sécurisés. Vous pouvez également utiliser un outil comme ngrok, localtunnel ou Hookdeck Console qui expose votre ordinateur local à Internet pour recevoir les charges utiles.

Création d’une URL de webhook avec Smee

Vous pouvez utiliser Smee pour créer un domaine unique dans lequel GitHub peut envoyer des charges utiles webhook, sans exposer votre développement local à Internet. Smee appelle ce domaine unique « URL de proxy webhook ». Vous pouvez utiliser l’URL du proxy webhook de Smee comme URL de webhook pour votre GitHub App.

1. Pour utiliser Smee pour créer un domaine unique, accédez à https://smee.io et cliquez sur Démarrer un nouveau canal.
2. Dans la page Canal Smee, suivez les instructions sous « Utiliser l’interface CLI » pour installer et exécuter le client Smee.
3. Pour connecter votre URL de webhook Smee à votre GitHub App, entrez votre domaine Smee unique dans le champ « URL webhook » de votre page d’inscription d’GitHub App Pour plus d’informations, consultez « Inscription d’une application GitHub » et « Modification d’une inscription d’application GitHub ».

Choix d’une URL de webhook pour la production

Pour une application en production qui reçoit un faible volume de trafic webhook, vous pouvez l’héberger sur n’importe quel serveur d’applications dynamique. Le code côté serveur pour la gestion du webhook peut recevoir l’événement, désérialiser sa charge utile JSON et décider de l’action à entreprendre, comme le stockage des données dans une base de données ou l’appel de l’API GitHub.

Pour gérer un volume plus élevé de trafic webhook pour une application volumineuse en production, envisagez d’utiliser la gestion de webhook asynchrone sur un serveur dédié. Vous pouvez y parvenir en utilisant une file d’attente, où le gestionnaire de webhook envoie des données à la file d’attente, et des processus distincts effectuent les actions suivantes en fonction des événements. En outre, vous pouvez utiliser des fonctions cloud, telles que Azure Functions, AWS Lambda ou Hookdeck, pour faciliter la mise à l’échelle de l’application afin de gérer de grands volumes d’événements de webhook.

Sécurisation de vos webhooks avec un secret de webhook

Une fois que votre serveur est configuré pour recevoir des charges utiles, il écoute toutes les charges utiles envoyées au serveur. Pour des raisons de sécurité, vous devez limiter les demandes entrantes uniquement à celles provenant de GitHub. Pour ce faire, créez un secret de webhook pour votre application.

Pour créer un secret de webhook pour votre application GitHub, tapez un jeton secret sous « Secret du webhook » sur votre page d’inscription d’GitHub App. Vous devez choisir une chaîne aléatoire de texte avec une entropie élevée. Pour plus d’informations, consultez « Inscription d’une application GitHub » et « Modification d’une inscription d’application GitHub ».

Après avoir créé un secret webhook pour votre application, vous devez configurer votre serveur pour stocker et valider de manière sécurisée le jeton secret webhook. Pour plus d’informations, consultez « Validation des livraisons de webhook ».

Abonnement aux événements de webhook

Vous pouvez vous abonner à votre GitHub App pour recevoir des charges utiles webhook pour des événements spécifiques. Les événements webhook spécifiques que vous pouvez sélectionner dans votre inscription d’GitHub App sont déterminés par le type d’autorisations que vous avez sélectionné pour votre application. Vous devez d’abord sélectionner les autorisations que vous souhaitez que votre application dispose, puis vous pouvez abonner votre application aux événements de webhook liés à cet ensemble d’autorisations. Pour plus d’informations, consultez « Choix des autorisations pour une application GitHub ».

Par exemple, si vous souhaitez que votre application reçoive une charge utile d’événement webhook chaque fois qu’un nouveau problème est ouvert dans votre référentiel, vous devez d’abord accorder à votre application l’autorisation d’accéder aux « problèmes » sous « Autorisations du référentiel ». Ensuite, sous « S’abonner aux événements », vous pouvez sélectionner « Problèmes ».

Pour plus d’informations sur les autorisations requises pour chaque événement de webhook, consultez « Événements et charges utiles du webhook ».