Ahora que entendemos lo básico de los webhooks, vamos a revisar el proceso de creación de nuestra propia integración impulsada por webhooks. 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 informes de problemas que recibe diariamente.
Crear un webhook es un proceso de dos pasos. Primero necesitas configurar la forma en la que quieres que se comporte tu webhook a través de GitHub Enterprise, es decir: a qué eventos quieres que escuche. Después, configurarás tu servidor para recibir y administrar la carga útil.
Configurar 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 ahí, da clic en Webhooks, y luego en Agregar webhook.
Como alternativa, puedes elegir el crear y administrar un webhook através de 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.
URL de la carga útil
La URL de carga útil es la URL del servidor que recibirá las solicitudes de POST del webhook.
Ya que estamos desarrollando todo localmente para nuestro tutorial, configurémosla como http://localhost:4567/payload. Te explicaremos por qué en los documentos de Configurar tu Servidor.
Tipo de Contenido
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. Para efecto de este tutorial, está bien si usas el tipo de contenido predeterminado de application/json.
Secreto
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".
Verificación de 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. Tienes la opción de inhabilitar SSL, pero te recomendamos que mantengas seleccionado 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.
Puedes encontrar un listado completo de eventos de webhook y del cuándo se ejecutan en la referencia de la API de webhooks.
Ya que nuestro webhook trata con informes de problemas en un repositorio, vamos a dar clic en Permíteme seleccionar eventos individuales y, posteriormente, en Informes de problemas. Asegúrate de seleccionar Activo para recibir eventos de los informes de problemas para los webhooks que se activen. También puedes seleccionar todos los eventos utilizando la opción predeterminada.
Cuando hayas terminado, da clic en Agregar webhook. ¡Uf! Ahora que creaste el webhook, es momento de configurar nuestro servidor local para probarlo. Dirígete a Configurar tu Servidor para aprender cómo hacerlo.
Evento de Comodín
Para configurar un webhook para todos los eventos, utiliza el caracter de comodín (*) para especificar dichos 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.