Now that we understand the basics of webhooks, let's go through the process of building out our own webhook-powered integration. In this tutorial, we'll create a repository webhook that will be responsible for listing out how popular our repository is, based on the number of issues it receives per day.
Creating a webhook is a two-step process. You'll first need to set up what events your webhook should listen to. After that, you'll set up your server to receive and manage the payload.
Vous pouvez utiliser l’API REST pour gérer les webhooks de dépôt, d’organisation et d’application. Vous pouvez lister les livraisons d’un webhook, ou obtenir et refaire une livraison individuelle d’un webhook, qui peut être intégré dans une application ou un service externe. Vous pouvez également utiliser l’API REST pour changer la configuration du webhook. Par exemple, vous pouvez modifier l’URL de charge utile, le type de contenu, la vérification SSL et le secret. Pour plus d'informations, consultez les pages suivantes :
Exposing localhost to the internet
For the purposes of this tutorial, we're going to use a local server to receive webhook events from GitHub.
First of all, we need to expose our local development environment to the internet so GitHub can deliver events. We'll use ngrok to do this.
Note: Alternatively, you can use webhook forwarding to set up your local environment to receive webhooks. For more information, see "Receiving webhooks with the GitHub CLI."
ngrok is available, free of charge, for all major operating systems. For more information, see the ngrok download page.
After installing ngrok, you can expose your localhost by running ./ngrok http 4567 on the command line. 4567 is the port number on which our server will listen for messages. You should see a line that looks something like this:
Forwarding http://7e9ea9dc.ngrok.io -> 127.0.0.1:4567
Make a note of the *.ngrok.io URL. We'll use it to set up our webhook.
Setting up a webhook
You can install webhooks on an organization or on a specific repository.
Seuls les membres avec des privilèges de propriétaire sur une organisation ou des privilèges d’administrateur sur un dépôt peuvent manage webhooks for an organization. Pour plus d’informations, consultez « Rôles dans une organisation ».
To set up a webhook, go to the settings page of your repository or organization. From there, click Webhooks, then Add webhook.
Alternatively, you can choose to build and manage a webhook through the Webhooks API.
Webhooks require a few configuration options before you can make use of them. We'll go through each of these settings below.
Payload URL
Remarque : les webhooks GitHub ne prennent actuellement pas en charge IPv6, mais le feront à l’avenir. Le point de terminaison d’API REST /meta retourne des plages IPv6 pour permettre cette transition.
L’URL de la charge utile est l’URL du serveur qui reçoit les requêtes POST des webhooks.
Since we're developing locally for our tutorial, we'll set it to the *.ngrok.io URL, followed by /payload. For example, http://7e9ea9dc.ngrok.io/payload.
Content type
Des webhooks peuvent être livrés à l’aide de différents types de contenus :
- Le type de contenu
application/jsonlivre la charge utile JSON directement comme corps de la demandePOST. - Le type de contenu
application/x-www-form-urlencodedenvoie la charge utile JSON en tant que paramètre de formulaire nommépayload.
Choisissez celle qui convient le mieux à vos besoins. For this tutorial, the default content type of application/json is fine.
Secret
La définition d’un secret de webhook vous permet de vous assurer que les requêtes POST envoyées à l’URL de charge utile proviennent de GitHub. Lorsque vous définissez un secret, vous recevez les en-têtes X-Hub-Signature et X-Hub-Signature-256 dans la requête POST du webhook. Pour plus d’informations sur l’utilisation d’un secret avec un en-tête de signature pour sécuriser vos charges utiles de webhook, consultez « Securing your webhooks ».
SSL verification
Si votre « URL de charge utile » est un site sécurisé (HTTPS), vous avez la possibilité de configurer les paramètres de vérification SSL. Si votre « URL de charge utile » n’est pas sécurisée (HTTP), GitHub n’affiche pas cette option. Par défaut, GitHub vérifie le certificat SSL de votre site web lors de la remise de charges utiles de webhook. La vérification SSL permet de s’assurer que les charges utiles de webhook sont remises au point de terminaison de votre URL de manière sécurisée. Vous avez la possibilité de désactiver SSL, mais nous vous recommandons de garder Activer la vérification SSL sélectionné.
Active
By default, webhook deliveries are "Active." You can choose to disable the delivery of webhook payloads by deselecting "Active."
Events
Events are at the core of webhooks. These webhooks fire whenever a certain action is taken on the repository, which your server's payload URL intercepts and acts upon.
A full list of webhook events, and when they execute, can be found in the webhooks API reference.
Since our webhook is dealing with issues in a repository, we'll click Let me select individual events and then Issues. Make sure you select Active to receive issue events for triggered webhooks. You can also select all events using the default option.
When you're finished, click Add webhook.
Now that you've created the webhook, it's time to set up our local server to test the webhook. Head on over to Configuring Your Server to learn how to do that.
Wildcard event
To configure a webhook for all events, use the wildcard (*) character to specify the webhook events. When you add the wildcard event, we'll replace any existing events you have configured with the wildcard event and send you payloads for all supported events. You'll also automatically get any new events we might add in the future.
Ping event
Lorsque vous créez un nouveau webhook, nous vous envoyons un simple événement ping pour vous informer que vous avez correctement configuré le webhook. Cet événement n’est pas stocké et ne peut donc pas être récupéré via le point de terminaison de l’API Événements.
For more information about the ping event webhook payload, see the ping event.