Gestion des livraisons de webhooks

Introduction

Lorsque vous créez un webhook, vous spécifiez une URL et vous vous abonnez à des types d’événements. Lorsqu’un événement auquel votre webhook est abonné se produit, GitHub envoie une requête HTTP avec des données sur l’événement à l’URL que vous avez spécifiée. Si votre serveur est configuré pour repérer les livraisons de webhook à cette URL, il peut prendre des mesures lorsqu’il en reçoit une.

Cet article explique comment écrire du code pour permettre à votre serveur de repérer et de répondre aux livraisons de webhook. Vous allez tester votre code à l’aide de votre ordinateur ou codespace en tant que serveur local.

Programme d’installation

Pour tester votre webhook en local, vous pouvez utiliser une URL proxy de webhook afin de rediriger les webhooks de GitHub vers votre ordinateur ou votre espace de code. Cet article utilise smee.io pour fournir une URL de proxy webhook et transférer des webhooks.

Obtenir une URL de proxy webhook

1. Dans votre navigateur, accédez à https://smee.io/.
2. Cliquez sur Démarrer un nouveau canal.
3. Copiez l’URL complète sous « URL du proxy webhook ». Vous utiliserez cette URL dans la procédure d’installation suivante.

Redirecteur des webhooks

1. Si vous n’avez pas déjà smee-client installé, exécutez la commande suivante dans votre terminal :

   Shell

   npm install --global smee-client
   

2. Pour recevoir des webhooks transférés à partir de smee.io, exécutez la commande suivante dans votre terminal. Remplacez WEBHOOK_PROXY_URL par l’URL de proxy de votre webhook précédent.

   Shell

   smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000
   

   Une sortie de ce type doit s’afficher, où WEBHOOK_PROXY_URL est l’URL de votre proxy webhook :

   Shell

   Forwarding WEBHOOK_PROXY_URL to http://127.0.0.1:3000/webhook
   Connected WEBHOOK_PROXY_URL
   

   Notez que le chemin d’accès est /webhook et que le port est 3000. Vous utiliserez ces valeurs ultérieurement lorsque vous écrivez du code pour gérer les livraisons de webhook.

3. Laissez-le tourner pendant que vous testez votre webhook. Lorsque vous souhaitez arrêter le transfert de webhooks, entrez Ctrl+C.

Créer un webhook

1. Créez un webhook avec les paramètres suivants : Pour plus d’informations, consultez « Création de webhooks ».

   • Pour l’URL, utilisez l’URL de votre proxy webhook à partir d’une version antérieure.
   • Si vous avez la possibilité de choisir le type de contenu, utilisez JSON.

Écrire du code pour gérer les livraisons de webhook

Pour gérer les livraisons de webhook, vous devez écrire du code qui :

• Initialise votre serveur pour repérer les demandes adressées à l’URL de votre webhook
• Lit les en-têtes HTTP et le corps de la requête
• Effectue l’action souhaitée en réponse à la demande

Vous pouvez utiliser n’importe quel langage de programmation que vous pouvez exécuter sur votre serveur.

Les exemples suivants impriment un message lorsqu’une livraison de webhook est reçue. Toutefois, vous pouvez modifier le code pour effectuer une autre action, comme effectuer une demande à l’API GitHub ou envoyer un message sur Slack.

• Exemple Ruby
• Exemple JavaScript

Exemple Ruby

Cet exemple utilise le gemme Ruby, Sinatra, pour définir des itinéraires et gérer des requêtes HTTP. Pour plus d’informations, consultez le fichier LISEZMOI de Sinatra.

Exemple de Ruby : installer des dépendances

Pour utiliser cet exemple, vous devez installer la gemme Sinatra dans votre projet Ruby. Vous pouvez par exemple effectuer cette opération avec Bundler :

1. Si Bundler n’est pas installé, exécutez la commande suivante dans votre terminal :

   Shell

   gem install bundler
   

2. Si un Gemfile n’est pas installé, exécutez la commande suivante dans votre terminal :

   Shell

   bundle init
   

3. Si un Gemfile.lock n’est pas installé, exécutez la commande suivante dans votre terminal :

   Shell

   bundle install
   

4. Installez le gemme Sinatra en exécutant la commande suivante dans votre terminal :

   Shell

   bundle add sinatra
   

Exemple de Ruby : écrire le code

Créez un fichier Ruby avec les contenus suivants : Modifiez le code pour gérer les types d’événements auxquels votre webhook est abonné, ainsi que l’événement ping que GitHub envoie lorsque vous créez un webhook. Cet exemple gère les événements issues et ping.

# These are the dependencies for this code. You installed the `sinatra` gem earlier. For more information, see [Ruby example: Install dependencies](#ruby-example-install-dependencies). The `json` library is a standard Ruby library, so you don't need to install it.
require 'sinatra'
require 'json'

# The `/webhook` route matches the path that you specified for the smee.io forwarding. For more information, see [Forward webhooks](#forward-webhooks).
#
# Once you deploy your code to a server and update your webhook URL, you should change this to match the path portion of the URL for your webhook.
post '/webhook' do

  # Respond to indicate that the delivery was successfully received.
  # Your server should respond with a 2XX response within 30 seconds of receiving a webhook delivery. If your server takes longer than that to respond, then GitHub terminates the connection and considers the delivery a failure.
  status 202

  # Check the `X-GitHub-Event` header to learn what event type was sent.
  # Sinatra changes `X-GitHub-Event` to `HTTP_X_GITHUB_EVENT`.
  github_event = request.env['HTTP_X_GITHUB_EVENT']

  # You should add logic to handle each event type that your webhook is subscribed to.
  # For example, this code handles the `issues` and `ping` events.
  #
  # If any events have an `action` field, you should also add logic to handle each action that you are interested in.
  # For example, this code handles the `opened` and `closed` actions for the `issue` event.
  #
  # For more information about the data that you can expect for each event type, see [AUTOTITLE](/webhooks/webhook-events-and-payloads).
  if github_event == "issues"
    data = JSON.parse(request.body.read)
    action = data['action']
    if action == "opened"
      puts "An issue was opened with this title: #{data['issue']['title']}"
    elsif action == "closed"
      puts "An issue was closed by #{data['issue']['user']['login']}"
    else
      puts "Unhandled action for the issue event: #{action}"
    end
  elsif github_event == "ping"
    puts "GitHub sent the ping event"
  else
    puts "Unhandled event: #{github_event}"
  end
end

require 'sinatra'
require 'json'

post '/webhook' do

  status 202

  github_event = request.env['HTTP_X_GITHUB_EVENT']

  if github_event == "issues"
    data = JSON.parse(request.body.read)
    action = data['action']
    if action == "opened"
      puts "An issue was opened with this title: #{data['issue']['title']}"
    elsif action == "closed"
      puts "An issue was closed by #{data['issue']['user']['login']}"
    else
      puts "Unhandled action for the issue event: #{action}"
    end
  elsif github_event == "ping"
    puts "GitHub sent the ping event"
  else
    puts "Unhandled event: #{github_event}"
  end
end

# These are the dependencies for this code. You installed the `sinatra` gem earlier. For more information, see [Ruby example: Install dependencies](#ruby-example-install-dependencies). The `json` library is a standard Ruby library, so you don't need to install it.
require 'sinatra'
require 'json'

# The `/webhook` route matches the path that you specified for the smee.io forwarding. For more information, see [Forward webhooks](#forward-webhooks).
#
# Once you deploy your code to a server and update your webhook URL, you should change this to match the path portion of the URL for your webhook.
post '/webhook' do

  # Respond to indicate that the delivery was successfully received.
  # Your server should respond with a 2XX response within 30 seconds of receiving a webhook delivery. If your server takes longer than that to respond, then GitHub terminates the connection and considers the delivery a failure.
  status 202

  # Check the `X-GitHub-Event` header to learn what event type was sent.
  # Sinatra changes `X-GitHub-Event` to `HTTP_X_GITHUB_EVENT`.
  github_event = request.env['HTTP_X_GITHUB_EVENT']

  # You should add logic to handle each event type that your webhook is subscribed to.
  # For example, this code handles the `issues` and `ping` events.
  #
  # If any events have an `action` field, you should also add logic to handle each action that you are interested in.
  # For example, this code handles the `opened` and `closed` actions for the `issue` event.
  #
  # For more information about the data that you can expect for each event type, see [AUTOTITLE](/webhooks/webhook-events-and-payloads).
  if github_event == "issues"
    data = JSON.parse(request.body.read)
    action = data['action']
    if action == "opened"
      puts "An issue was opened with this title: #{data['issue']['title']}"
    elsif action == "closed"
      puts "An issue was closed by #{data['issue']['user']['login']}"
    else
      puts "Unhandled action for the issue event: #{action}"
    end
  elsif github_event == "ping"
    puts "GitHub sent the ping event"
  else
    puts "Unhandled event: #{github_event}"
  end
end

Exemple de Ruby : tester le code

Pour tester votre webhook, vous pouvez utiliser votre ordinateur ou codespace pour agir en tant que serveur local. Si vous rencontrez des problèmes avec ces étapes, consultez Dépannage.

1. Vérifiez que vous avez correctement activé le transfert des webhooks. Si vous ne transférez plus de webhooks, suivez à nouveau les étapes décrites dans Transférer des webhooks .

2. Dans une fenêtre de terminal distincte, exécutez la commande suivante pour démarrer un serveur local sur votre ordinateur ou codespace. Remplacez FILE_PATH par le chemin d’accès au fichier dans lequel est stocké le code de la section précédente. Notez que PORT=3000 correspond au port que vous avez spécifié pour le transfert du webhook à l’étape précédente.

   Shell

   PORT=3000 ruby FILE_NAME
   

   Un message devrait apparaître indiquant quelque chose comme « Sinatra a pris le relais sur 3000 ».

3. Déclenchez votre webhook. Par exemple, si vous avez créé un webhook de référentiel abonné à l’événement issues, ouvrez un problème dans votre référentiel. Vous pouvez également livrer de nouveau des livraisons précédentes de webhooks. Pour plus d’informations, consultez « Nouvelle livraison des webhooks ».

4. Accédez à l’URL du proxy de votre webhook sur smee.io. Vous devriez voir un événement qui correspond à l’événement que vous avez déclenché ou renvoyé. Cela indique que GitHub a correctement envoyé une livraison de webhook à l’URL de charge utile que vous avez spécifiée.

5. Dans la fenêtre du terminal où vous avez exécuté la commande smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000, vous devriez voir quelque chose comme POST http://127.0.0.1:3000/webhook - 202. Cela indique que smee a transféré avec succès votre webhook dans votre serveur local.

6. Dans la fenêtre de terminal où vous avez exécuté la commande PORT=3000 ruby FILE_NAME, vous devriez voir un message correspondant à l’événement qui a été envoyé. Par exemple, si vous utilisez l’exemple de code ci-dessus et que vous avez livré de nouveau l’événement ping, vous devriez voir « GitHub a envoyé l’événement ping ». Vous pouvez également voir d’autres lignes que Sinatra imprime automatiquement.

7. Dans les deux fenêtres du terminal, entrez Ctrl+C pour arrêter votre serveur local et arrêter de repérer des webhooks transférés.

Maintenant que vous avez testé votre code localement, vous pouvez le modifier pour utiliser votre webhook en production. Pour plus d’informations, consultez Étapes suivantes. Si vous avez eu des difficultés à tester votre code, essayez les étapes décrites dans « Résolution des problèmes ».

Exemple JavaScript

Cet exemple utilise Node.js et la bibliothèque Express pour définir des itinéraires et gérer les requêtes HTTP. Pour plus d’informations, consultez « expressjs.com ».

Pour un exemple qui utilise GitHub le SDK Octokit.js, voir Création d’une application GitHub qui répond aux événements de webhook.

Cet exemple nécessite que votre ordinateur ou codespace exécute Node.js version 12 ou ultérieure et npm version 6.12.0 ou ultérieure. Pour plus d’informations, consultez Node.js.

Exemple JavaScript : installer les dépendances

Pour utiliser cet exemple, vous devez installer la bibliothèque express dans votre projet Node.js. Par exemple :

npm install express

npm install express

Exemple JavaScript : écrire le code

Créez un fichier JavaScript avec le contenu suivant : Modifiez le code pour gérer les types d’événements auxquels votre webhook est abonné, ainsi que l’événement ping que GitHub envoie lorsque vous créez un webhook. Cet exemple gère les événements issues et ping.

// You installed the `express` library earlier. For more information, see [JavaScript example: Install dependencies](#javascript-example-install-dependencies).
const express = require('express');

// This initializes a new Express application.
const app = express();

// This defines a POST route at the `/webhook` path. This path matches the path that you specified for the smee.io forwarding. For more information, see [Forward webhooks](#forward-webhooks).
//
// Once you deploy your code to a server and update your webhook URL, you should change this to match the path portion of the URL for your webhook.
app.post('/webhook', express.json({type: 'application/json'}), (request, response) => {

  // Respond to indicate that the delivery was successfully received.
  // Your server should respond with a 2XX response within 30 seconds of receiving a webhook delivery. If your server takes longer than that to respond, then GitHub terminates the connection and considers the delivery a failure.
  response.status(202).send('Accepted');

  // Check the `x-github-event` header to learn what event type was sent.
  const githubEvent = request.headers['x-github-event'];

  // You should add logic to handle each event type that your webhook is subscribed to.
  // For example, this code handles the `issues` and `ping` events.
  //
  // If any events have an `action` field, you should also add logic to handle each action that you are interested in.
  // For example, this code handles the `opened` and `closed` actions for the `issue` event.
  //
  // For more information about the data that you can expect for each event type, see [AUTOTITLE](/webhooks/webhook-events-and-payloads).
  if (githubEvent === 'issues') {
    const data = request.body;
    const action = data.action;
    if (action === 'opened') {
      console.log(`An issue was opened with this title: ${data.issue.title}`);
    } else if (action === 'closed') {
      console.log(`An issue was closed by ${data.issue.user.login}`);
    } else {
      console.log(`Unhandled action for the issue event: ${action}`);
    }
  } else if (githubEvent === 'ping') {
    console.log('GitHub sent the ping event');
  } else {
    console.log(`Unhandled event: ${githubEvent}`);
  }
});

// This defines the port where your server should listen.
// 3000 matches the port that you specified for webhook forwarding. For more information, see [Forward webhooks](#forward-webhooks).
//
// Once you deploy your code to a server, you should change this to match the port where your server is listening.
const port = 3000;

// This starts the server and tells it to listen at the specified port.
app.listen(port, () => {
  console.log(`Server is running on port ${port}`);
});

const express = require('express');

const app = express();

app.post('/webhook', express.json({type: 'application/json'}), (request, response) => {

  response.status(202).send('Accepted');

  const githubEvent = request.headers['x-github-event'];

  if (githubEvent === 'issues') {
    const data = request.body;
    const action = data.action;
    if (action === 'opened') {
      console.log(`An issue was opened with this title: ${data.issue.title}`);
    } else if (action === 'closed') {
      console.log(`An issue was closed by ${data.issue.user.login}`);
    } else {
      console.log(`Unhandled action for the issue event: ${action}`);
    }
  } else if (githubEvent === 'ping') {
    console.log('GitHub sent the ping event');
  } else {
    console.log(`Unhandled event: ${githubEvent}`);
  }
});

const port = 3000;

app.listen(port, () => {
  console.log(`Server is running on port ${port}`);
});

// You installed the `express` library earlier. For more information, see [JavaScript example: Install dependencies](#javascript-example-install-dependencies).
const express = require('express');

// This initializes a new Express application.
const app = express();

// This defines a POST route at the `/webhook` path. This path matches the path that you specified for the smee.io forwarding. For more information, see [Forward webhooks](#forward-webhooks).
//
// Once you deploy your code to a server and update your webhook URL, you should change this to match the path portion of the URL for your webhook.
app.post('/webhook', express.json({type: 'application/json'}), (request, response) => {

  // Respond to indicate that the delivery was successfully received.
  // Your server should respond with a 2XX response within 30 seconds of receiving a webhook delivery. If your server takes longer than that to respond, then GitHub terminates the connection and considers the delivery a failure.
  response.status(202).send('Accepted');

  // Check the `x-github-event` header to learn what event type was sent.
  const githubEvent = request.headers['x-github-event'];

  // You should add logic to handle each event type that your webhook is subscribed to.
  // For example, this code handles the `issues` and `ping` events.
  //
  // If any events have an `action` field, you should also add logic to handle each action that you are interested in.
  // For example, this code handles the `opened` and `closed` actions for the `issue` event.
  //
  // For more information about the data that you can expect for each event type, see [AUTOTITLE](/webhooks/webhook-events-and-payloads).
  if (githubEvent === 'issues') {
    const data = request.body;
    const action = data.action;
    if (action === 'opened') {
      console.log(`An issue was opened with this title: ${data.issue.title}`);
    } else if (action === 'closed') {
      console.log(`An issue was closed by ${data.issue.user.login}`);
    } else {
      console.log(`Unhandled action for the issue event: ${action}`);
    }
  } else if (githubEvent === 'ping') {
    console.log('GitHub sent the ping event');
  } else {
    console.log(`Unhandled event: ${githubEvent}`);
  }
});

// This defines the port where your server should listen.
// 3000 matches the port that you specified for webhook forwarding. For more information, see [Forward webhooks](#forward-webhooks).
//
// Once you deploy your code to a server, you should change this to match the port where your server is listening.
const port = 3000;

// This starts the server and tells it to listen at the specified port.
app.listen(port, () => {
  console.log(`Server is running on port ${port}`);
});

Exemple JavaScript : tester le code

Pour tester votre webhook, vous pouvez utiliser votre ordinateur ou codespace pour agir en tant que serveur local. Si vous rencontrez des problèmes avec ces étapes, consultez Dépannage.

1. Vérifiez que vous avez correctement activé le transfert des webhooks. Si vous ne transférez plus de webhooks, suivez à nouveau les étapes décrites dans Transférer des webhooks .

2. Dans une fenêtre de terminal distincte, exécutez la commande suivante pour démarrer un serveur local sur votre ordinateur ou codespace. Remplacez FILE_PATH par le chemin d’accès au fichier dans lequel est stocké le code de la section précédente.

   Shell

   node FILE_NAME
   

   Vous devriez voir la sortie qui indique Server is running on port 3000.

3. Déclenchez votre webhook. Par exemple, si vous avez créé un webhook de référentiel abonné à l’événement issues, ouvrez un problème dans votre référentiel. Vous pouvez également livrer de nouveau des livraisons précédentes de webhooks. Pour plus d’informations, consultez « Nouvelle livraison des webhooks ».

4. Accédez à l’URL du proxy de votre webhook sur smee.io. Vous devriez voir un événement qui correspond à l’événement que vous avez déclenché ou renvoyé. Cela indique que GitHub a correctement envoyé une livraison de webhook à l’URL de charge utile que vous avez spécifiée.

5. Dans la fenêtre du terminal où vous avez exécuté la commande smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000, vous devriez voir quelque chose comme POST http://127.0.0.1:3000/webhook - 202. Cela indique que smee a transféré avec succès votre webhook dans votre serveur local.

6. Dans la fenêtre de terminal où vous avez exécuté la commande node FILE_NAME, vous devriez voir un message correspondant à l’événement qui a été envoyé. Par exemple, si vous utilisez l’exemple de code ci-dessus et que vous avez livré de nouveau l’événement ping, vous devriez voir « GitHub a envoyé l’événement ping ».

7. Dans les deux fenêtres du terminal, entrez Ctrl+C pour arrêter votre serveur local et arrêter de repérer des webhooks transférés.

Maintenant que vous avez testé votre code localement, vous pouvez le modifier pour utiliser votre webhook en production. Pour plus d’informations, consultez Étapes suivantes. Si vous avez eu des difficultés à tester votre code, essayez les étapes décrites dans « Résolution des problèmes ».

Dépannage

Si vous ne voyez pas les résultats attendus décrits dans les étapes de test, essayez ce qui suit :

• Assurez-vous que votre webhook utilise l’URL de votre proxy webhook (Smee.io URL). Pour plus d’informations sur l’URL de votre proxy webhook, consultez « Obtenir une URL de proxy webhook ». Pour plus d’informations sur les paramètres de votre webhook, consultez « Création de webhooks ».
• Si vous avez le choix entre le type de contenu à utiliser, assurez-vous que votre webhook utilise le type de contenu JSON. Pour plus d’informations sur les paramètres de votre webhook, consultez « Création de webhooks ».
• Assurez-vous que le client smee et votre serveur local sont en cours d’exécution. Ces deux processus s’exécuteront dans deux fenêtres différentes du terminal.
• Assurez-vous que votre serveur écoute le même port que celui vers lequel smee.io transfère les webhooks. Tous les exemples dans cet article utilisent le port 3000.
• Vérifiez que le chemin d’accès vers lequel smee.io transfère les webhooks correspond à un itinéraire défini dans votre code. Tous les exemples de cet article utilisent le chemin d’accès /webhooks.
• Recherchez des messages d’erreur dans les fenêtres du terminal où vous exécutez le client smee et votre serveur local.
• Contrôlez GitHub pour vérifier qu’une livraison de webhook a été déclenchée. Pour plus d’informations, consultez « Affichage des livraisons de webhook ».
• Accédez à l’URL du proxy de votre webhook sur smee.io. Vous devriez voir un événement qui correspond à l’événement que vous avez déclenché ou renvoyé. Cela indique que GitHub a correctement envoyé une livraison de webhook à l’URL de charge utile que vous avez spécifiée.

Étapes suivantes

Cet article a montré comment écrire du code pour gérer les livraisons de webhook. Il a également montré comment tester votre code à l’aide de votre ordinateur ou codespace en tant que serveur local et en transférant des livraisons de webhook de GitHub à votre serveur local via smee.io. Une fois que vous avez terminé de tester votre code, vous pouvez modifier le code et le déployer sur un serveur.

Modifier ce code.

Cet article fournit des exemples de base qui impriment un message lorsqu’une livraison de webhook est reçue. Vous pouvez modifier le code pour effectuer une autre action. Par exemple, vous pouvez modifier le code pour :

• Effectuer une demande à l’API GitHub
• Envoyer un message sur Slack
• Événements de journalisation
• Mettre à jour un outil de gestion de projet externe

Vérifier que la livraison provient de GitHub

Dans votre code qui gère les livraisons de webhook, vous devriez confirmer que la livraison provient de GitHub avant de traiter la livraison. Pour plus d’informations, consultez « Validation des livraisons de webhook ».

Déployer votre code sur un serveur

Cet article a montré comment utiliser votre ordinateur ou codespace en tant que serveur pendant que vous développez votre code. Une fois que le code est prêt à être mis en application, vous devriez déployer votre code sur un serveur dédié.

Lorsque vous le faites, vous devrez peut-être mettre à jour votre code pour refléter l’hôte et le port où votre serveur opère.

Mettre à jour l’URL du webhook

Une fois que vous disposez d’un serveur configuré pour recevoir le trafic webhook à partir de GitHub, mettez à jour l’URL dans les paramètres de votre webhook. Vous devrez peut-être mettre à jour l’itinéraire géré par votre code pour qu’il corresponde à la partie de chemin d’accès de la nouvelle URL. Par exemple, si votre nouvelle URL de webhook est https://example.com/github-webhooks, vous devez modifier l’itinéraire dans ces exemples de /webhooks à /github-webhooks.

Vous ne devriez pas utiliser smee.io pour transférer vos webhooks en production.

Suivre les bonnes pratiques

Vous devriez chercher à suivre les meilleures pratiques pour vos webhooks. Pour plus d’informations, consultez « Meilleures pratiques en matière d’utilisation des webhooks ».

Pour aller plus loin

• Création d’une application GitHub qui répond aux événements de webhook
• Meilleures pratiques en matière d’utilisation des webhooks