Skip to main content

Creating webhooks

Learn to build a webhook, choosing the events your webhook will listen for on GitHub and how to set up a server to receive and manage the webhook payload.

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.

Puedes usar la API de REST para administrar repositorios, organizaciones y webhooks de aplicaciones. Puedes enumerar las entregas de webhook para un webhook, o bien obtener y volver a entregar una entrega individual para un webhook, que se puede integrar en una aplicación o servicio externos. También puedes usar la API REST para cambiar la configuración del webhook. Por ejemplo, puedes modificar la URL de la carga útil, el tipo de contenido, la verificación de SSL, y el secreto. Para más información, consulte:

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.

Solo los miembros con privilegios de propietario de una organización o privilegios de administrador de un repositorio pueden manage webhooks for an organization. Para obtener más información, vea «Roles en una organización».

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

Nota: Los webhooks de GitHub actualmente no son compatibles con IPv6, pero lo serán en el futuro. El punto de conexión de la API REST /meta devuelve intervalos IPv6 para habilitar esa transición.

La dirección URL de la carga es la dirección URL del servidor que va a recibir las solicitudes 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/json entregará la carga JSON directamente como el cuerpo de la solicitud POST.
  • El tipo de contenido application/x-www-form-urlencoded enviará la carga JSON como un parámetro de formulario denominado payload.

Elija el que mejor se ajuste a sus necesidades. For this tutorial, the default content type of application/json is fine.

Secret

Configurar un secreto de webhook permite garantizar que las solicitudes POST que se enviaron a la URL de la carga útil sean de GitHub. Al establecer un secreto, recibirá los encabezados X-Hub-Signature y X-Hub-Signature-256, y el encabezado en la solicitud POST de webhook. Para más información de cómo usar un secreto con un encabezado de firma para proteger las cargas de webhook, consulta "Securing your 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. Tiene la opción de deshabilitar SSL, pero le recomendamos que mantenga seleccionado Enable SSL verification (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.

Ping event

Cuando crea un webhook, le enviaremos un evento de ping sencillo para informarle que ha configurado el webhook correctamente. Este evento no se almacena, por lo que no se puede recuperar mediante el punto de conexión de la API de Eventos.

For more information about the ping event webhook payload, see the ping event.

⌂ Proxy