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 how you want your webhook to behave through GitHub Enterprise: what events should it listen to. After that, you'll set up your server to receive and manage the payload.
You can use the repository, organization, and app webhook REST APIs to create, update, delete, and ping webhooks. You can also use the REST API to change the configuration of the webhook. For example, you can modify the payload URL, content type, SSL verification, and secret. For more information, see:
Exposing localhost to the internet
For the purposes of this tutorial, we're going to use a local server to receive messages from GitHub. So, first of all, we need to expose our local development environment to the internet. We'll use ngrok to do this. 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:4567Make 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.
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
La URL de carga útil es la URL del servidor que recibirá las solicitudes de POST del webhook.
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
Los webhooks pueden entregarse utilizando diferentes tipos de contenido:
- El tipo de contenido
application/jsonentregará la carga útil de JSON directametne como el cuerpo de la solicitudPOST. - El tipo de contenido
application/x-www-form-urlencodedenviará la carga útil de JSON como un parámetro de forma llamadopayload.
Elige el que se adapte mejor a tus necesidades. For this tutorial, the default content type of application/json is fine.
Secret
Configurar el secreto de un webhook te permite garantizar que las solicitudes de POST que se envían a la URL de la carga útil vienen de GitHub. Cuando configuras un secreto, recibirás el encabezado de X-Hub-Signature en el la solicitud de POST del webhook. Para obtener más detalles sobre cómo utilizar el secreto y el encabezado de X-Hub-Signature para asegurar las cargas útiles de tu webhook, consulta la sección "Asegurar tus webhooks".
SSL verification
Si tu "URL de carga útil" es un sitio seguro (HTTPS), tendrás la opción de configurar los ajustes de verificación de SSL. Si tu "URL de carga útil" no es segura (HTTP), GitHub no mostrará esta opción. Predeterminadamente, GitHub verifica el certificado SSL de tu sitio web cuando entrega cargas útiles de webhooks. La verificación de SSL ayuda a garantizar que las cargas útiles de los ganchos se entregan en tu terminal URL de forma segura. Tienes la opción de inhabilitar SSL, pero te recomendamos que mantengas seleccionado Habilitar la verificación SSL.
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.