Ahora que entendemos los conceptos básicos de los webhooks, vamos a recorrer el proceso de creación de nuestra propia integración con tecnología de webhook. En este tutorial, crearemos un webhook de repositorio que será responsable de listar qué tan popular es nuestro repositorio con base en la cantidad de propuestas que recibe diariamente.
Crear un webhook es un proceso de dos pasos. En primer lugar, deberás configurar los eventos que debe escuchar el webhook. Después, configurarás tu servidor para recibir y administrar la carga útil.
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:
Exponer un host local al internet
Para los propósitos de este tutorial, utilizaremos un servidor local para recibir eventos de webhook de GitHub.
En primer lugar, es necesario exponer nuestro entorno de desarrollo local a Internet para que GitHub pueda entregar eventos. Utilizaremos ngrok para hacerlo.
Nota: Como alternativa, puedes usar el reenvío de webhooks para configurar el entorno local para recibir webhooks. Para obtener más información, vea «Recepción de webhooks con la CLI de GitHub».
ngrok está disponible, gratuitamente, para los sistemas operativos principales. Para obtener más información, consulte la página de descarga de ngrok.
Después de instalar ngrok, puede exponer el host local ejecutando ./ngrok http 4567 en la línea de comandos. 4567 es el número de puerto en el que nuestro servidor escuchará mensajes. Deberías ver una línea que se ve más o menos así:
$ Forwarding http://7e9ea9dc.ngrok.io -> 127.0.0.1:4567Anote los valores de la dirección URL de *.ngrok.io. La utilizaremos para configurar nuestro webhook.
Configuración de un webhook
Puedes instalar webhooks en una organización o en un repositorio específico.
Para configurar un webhook, ve a la página de configuración de tu repositorio u organización. Desde allí, haga clic en Webhooks y, a continuación, en Add webhook.
También puede elegir compilar y administrar un webhook desde la API de webhooks.
Los Webhooks necesitan configurar algunas de sus opciones antes de que los puedas utilizar. Vamos a ver cada una de éstas opciones a continuación.
Dirección URL de carga
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.
Dado que estamos desarrollando a nivel local para nuestro tutorial, lo estableceremos en la dirección URL de *.ngrok.io, seguida de /payload. Por ejemplo, http://7e9ea9dc.ngrok.io/payload.
Tipo de contenido
Los webhooks pueden entregarse utilizando diferentes tipos de contenido:
- El tipo de contenido
application/jsonentregará la carga JSON directamente como el cuerpo de la solicitudPOST. - El tipo de contenido
application/x-www-form-urlencodedenviará la carga JSON como un parámetro de formulario denominadopayload.
Elija el que mejor se ajuste a sus necesidades. Para este tutorial, el tipo de contenido predeterminado application/json está bien.
Secreto
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 (Protección de sus webhooks)".
Verificación SSL
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).
Activo
Predeterminadamente, las entregas de webhook están "Activas". También puedes elegir inhabilitar la entrega de cargas útiles de webhooks si deseleccionas "Activo".
Eventos
Los eventos son el núcleo de los webhooks. Estos webhooks se disparan cuando se toma alguna acción específica en el repositorio, la cual intercepta tu URL de carga útil de l servidor para actuar sobre ella.
Encontrará una lista completa de eventos de webhook, especificando cuándo se ejecutan, en la referencia de la API de webhooks.
Dado que nuestro webhook gestiona las incidencias de un repositorio, haremos clic en Let me select individual events y, a continuación, en Issues. Asegúrese de seleccionar Active (Activo) para recibir eventos de problema para los webhook desencadenados. También puedes seleccionar todos los eventos utilizando la opción predeterminada.
Cuando haya terminado, haga clic en Add webhook.
Ahora que creaste el webhook, es momento de configurar nuestro servidor local para probarlo. Vaya a Configuración del servidor para saber cómo hacerlo.
Evento de comodín
Para configurar un webhook para todos los eventos, utilice el carácter comodín (*) para especificar los eventos. Cuando agregas el evento de comodín, reemplazaremos cualquier evento existente que hayas configurado con el evento de comodín se te enviarán las cargas útiles para todos los eventos compatibles. También obtendrás automáticamente cualquier evento nuevo que pudiéramos agregar posteriormente.