Maintenant que nous avons vu les concepts de base des webhooks, voyons le processus de création de notre propre intégration basée sur un webhook. Dans ce tutoriel, nous créons un webhook de dépôt chargé de lister la popularité de notre dépôt, en fonction du nombre de problèmes qu’il reçoit par jour.
La création d’un webhook se déroule en deux étapes. Vous devez d’abord configurer les événements que votre webhook doit écouter. Ensuite, vous configurez votre serveur pour recevoir et gérer la charge utile.
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 :
Exposition de localhost sur Internet
Dans le cadre de ce tutoriel, nous allons utiliser un serveur local pour recevoir les événements de webhook GitHub.
Tout d’abord, nous devons exposer notre environnement de développement local sur Internet afin que GitHub puisse fournir des événements. Pour ce faire, nous allons utiliser ngrok.
ngrok est disponible gratuitement pour tous les principaux systèmes d’exploitation. Pour plus d’informations, consultez la page de téléchargement de ngrok.
Après l’installation de ngrok, vous pouvez exposer votre localhost en exécutant ./ngrok http 4567 sur la ligne de commande. 4567 est le numéro de port sur lequel notre serveur écoute les messages. Vous devez voir une ligne qui ressemble à ceci :
$ Forwarding http://7e9ea9dc.ngrok.io -> 127.0.0.1:4567Notez l’URL *.ngrok.io. Nous l’utilisons pour configurer notre webhook.
Configuration d’un webhook
Vous pouvez installer des webhooks sur une organisation ou sur un dépôt spécifique.
Pour configurer un webhook, accédez à la page de paramètres de votre dépôt ou organisation. À partir de là, cliquez sur Webhooks, puis Ajouter un webhook.
Vous pouvez aussi choisir de créer et gérer un webhook avec l’API Webhooks.
Les webhooks nécessitent quelques options de configuration avant de pouvoir être utilisés. Nous examinons chacun de ces paramètres ci-dessous.
URL de la charge utile
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.
Comme nous développons localement dans le cadre de notre tutoriel, nous la définissons sur l’URL *.ngrok.io, suivie de /payload. Par exemple : http://7e9ea9dc.ngrok.io/payload.
Type de contenu
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. Pour ce tutoriel, le type de contenu par défaut application/json convient.
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 AE. Lorsque vous définissez un secret, vous recevez l’en-têteX-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 « Sécurisation de vos webhooks ».
Vérification SSL
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é.
Actif
Par défaut, la livraison de webhook est « Active ». Vous pouvez choisir de désactiver la livraison des charges utiles de webhook en désélectionnant « Active ».
Événements
Les événements sont au cœur des webhooks. Ces webhooks se déclenchent chaque fois qu’une certaine action est effectuée sur le dépôt, que l’URL de charge utile de votre serveur intercepte et à partir de laquelle elle exécute une action.
Pour voir la liste complète des événements de webhook et savoir quand ils s’exécutent, consultez la documentation de référence de l’API Webhooks.
Comme notre webhook traite les problèmes dans un dépôt, nous cliquons sur Me permettre de sélectionner des événements individuels, puis Problèmes. Sélectionnez Active pour recevoir les événements liés aux problèmes concernant les webhooks déclenchés. Vous pouvez également sélectionner tous les événements en utilisant l’option par défaut.
Quand vous avez fini, cliquez sur Ajouter un webhook.
Maintenant que vous avez créé le webhook, vous pouvez configurer le serveur local pour tester le webhook. Consultez Configuration de votre serveur pour savoir comment faire.
Événement générique
Pour configurer un webhook pour tous les événements, utilisez le caractère générique (*) afin de spécifier les événements de webhook. Quand vous ajoutez l’événement générique, nous remplaçons tous les événements existants que vous avez configurés par l’événement générique et vous envoyons des charges utiles pour tous les événements pris en charge. Vous obtenez également automatiquement tous les nouveaux événements ajoutés par la suite.