À propos des webhooks et GitHub Apps
Les webhooks permettent à votre GitHub App de recevoir des notifications en temps réel lorsque certains événements se produisent sur GitHub, par exemple lorsqu’une personne effectue un commit ou ouvre une pull request dans un dépôt auquel votre application peut accéder. Pour plus d’informations sur les webhooks, consultez À propos des webhooks. Pour obtenir un didacticiel qui montre comment utiliser des webhooks avec un GitHub App, consultez Création 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 déclencher automatiquement des actions en conséquence. 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 enregistrement GitHub App et spécifier une URL de webhook vers laquelle GitHub enverra les charges utiles des webhooks.
Si votre GitHub App n’a pas besoin de répondre aux webhooks ou ne sera utilisé que pour l’authentification, vous pouvez désactiver la fonctionnalité webhook pour l’enregistrement de votre GitHub App. Vous n’avez pas besoin de spécifier une URL de webhook.
Pour plus d’informations sur l’inscription d’un GitHub App, consultez Inscription d’une application GitHub. Pour plus d’informations sur la façon de modifier les webhooks auxquels un GitHub App enregistrement s’abonne, consultez Modification d’une inscription d’application GitHub.
Choix d’une URL de webhook
Lorsque vous activez des webhooks pour votre GitHub App inscription, vous devez spécifier une URL de webhook. L’URL du webhook est l’adresse d’un serveur web qui recevra les charges utiles de l’é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 adapté au volume de trafic des webhooks que votre GitHub App devra gérer.
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 vers lequel GitHub peut envoyer des charges utiles de webhook, sans exposer votre environnement de 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.
- Pour utiliser Smee pour créer un domaine unique, accédez à https://smee.io et cliquez sur Démarrer un nouveau canal.
- Dans la page Canal Smee, suivez les instructions sous « Utiliser l’interface CLI » pour installer et exécuter le client Smee.
- Pour connecter l’URL de votre webhook Smee à votre GitHub App, saisissez votre domaine Smee unique dans le champ « URL du webhook » de la page d’inscription de votre 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 permettant de gérer le webhook peut recevoir l’événement, désérialiser sa charge utile JSON et décider de l’action à entreprendre, telle que 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 aider à mettre à l’échelle l’application pour gérer de grands volumes d’événements 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 requêtes entrantes aux seules demandes provenant de GitHub. Pour ce faire, créez un secret de webhook pour votre application.
Pour créer un secret webhook pour votre application GitHub, tapez un jeton secret sous « Secret Webhook » sur votre GitHub App page d’inscription. 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 abonner votre GitHub App pour recevoir des charges utiles envoyées par webhook pour certains événements. 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 ».