Acerca de webhooks y GitHub Apps
Los webhooks permiten que tu GitHub App reciba notificaciones en tiempo real cuando se produzcan eventos en GitHub, como cuando alguien inserta una confirmación o abre una solicitud de incorporación de cambios en un repositorio al que la aplicación puede acceder. Para obtener más información sobre los webhooks, consulta "Acerca de webhooks".
Puedes configurar tu GitHub App para recibir webhooks para eventos específicos en GitHub y tomar medidas automáticamente en ellos. Para obtener más información sobre los tipos de webhooks que puedes recibir, consulta "Eventos y cargas de webhook".
Para recibir eventos de webhook en tu GitHub App, debes activar webhooks en la configuración de la aplicación y especificar una dirección URL de webhook donde GitHub enviará las cargas de webhook. Para obtener más información sobre la creación y configuración de una GitHub App, consulta "Crear una GitHub App".
Si la aplicación no necesita responder a webhooks o solo se va a usar para la autenticación, puedes desactivar la función de webhook en la configuración de dicha aplicación. No es necesario especificar una dirección URL de webhook. Para obtener más información, vea «Crear una GitHub App».
Para obtener información sobre cómo cambiar los webhooks a los que se suscribe una instancia de GitHub App, consulte "Modificar una GitHub App".
Elección de una dirección URL de webhook
Al activar webhooks en la configuración de tu GitHub App, deberás especificar una dirección URL de webhook. La dirección URL del webhook es la dirección de un servidor web que recibirá las cargas de eventos de webhook enviadas a tu GitHub App. A continuación, el servidor puede tomar medidas en función del contenido de la carga. Debes elegir un servidor web adecuado para el volumen de tráfico de webhook que tu GitHub App encontrará.
Elección de una dirección URL de webhook para desarrollo y pruebas
Mientras desarrollas y pruebas la aplicación, puedes usar un servicio de entrega de carga de webhook como Smee para capturar y reenviar cargas de webhook al entorno de desarrollo local. Nunca uses Smee para una aplicación en producción, ya que los canales Smee no están autenticados ni son seguros. Como alternativa, puedes usar una herramienta como ngrok, localtunnel o la consola de Hookdeck que expone la máquina local a Internet para recibir las cargas.
Creación de una dirección URL de webhook con Smee
Puedes usar Smee para crear un dominio único donde GitHub puede enviar cargas de webhook, sin exponer el desarrollo local a Internet. Smee denomina a este dominio único "dirección URL de proxy de webhook". Puedes usar la dirección URL del proxy de webhook de Smee como la dirección URL de webhook para tu GitHub App.
- Para usar Smee para crear un dominio único, ve a https://smee.io y haz clic en Iniciar un nuevo canal.
- En la página del canal de Smee, sigue las instrucciones que se encuentran en "Usar la CLI" para instalar y ejecutar el cliente de Smee.
- Para conectar la dirección URL del webhook de Smee a tu GitHub App, escribe tu dominio de Smee único en el campo "Dirección URL del webhook" de la configuración de la aplicación. Para obtener más información, vea «Crear una GitHub App».
Elección de una dirección URL de webhook para producción
Para una aplicación en producción que recibe un bajo volumen de tráfico de webhook, puedes hospedarla en cualquier servidor de aplicaciones dinámico. El código del lado servidor para controlar el webhook puede recibir el evento, deserializar su carga JSON y decidir qué acción realizar, como almacenar los datos en una base de datos o llamar a la API de GitHub.
Para controlar un mayor volumen de tráfico de webhook para una aplicación grande en producción, considera la posibilidad de usar el control de webhook asincrónico en un servidor dedicado. Para lograrlo, puedes emplear una cola, en la que el controlador de webhook inserta datos y los procesos independientes realizan acciones posteriores en función de los eventos. Además, puedes usar funciones en la nube como Azure Functions o AWS Lambda o Hookdeck para ayudar a escalar la aplicación para controlar grandes volúmenes de eventos de webhook.
Protección de los webhooks con un secreto de webhook
Una vez que hayas configurado el servidor para recibir las cargas, escuchará para cualquier carga que se envíe al servidor. Por motivos de seguridad, debes limitar las solicitudes entrantes solo a las que se originan en GitHub. Para ello, puedes crear un secreto de webhook para la aplicación.
Para crear un secreto de webhook para la aplicación de GitHub, escribe un token secreto en la configuración de la aplicación en "Secreto de webhook". Debes elegir una cadena aleatoria de texto con alta entropía. Para obtener más información sobre cómo crear un secreto de webhook en la configuración de la aplicación, consulta "Crear una GitHub App".
Después de crear un secreto de webhook para la aplicación, deberás configurar el servidor para almacenar y validar de forma segura el token secreto de webhook. Para obtener más información, vea «Securing your webhooks (Protección de sus webhooks)».
Suscripción a eventos de webhook
Puedes suscribir tu GitHub App para recibir cargas de webhook para eventos específicos. The specific webhook events that you can select in your app settings are determined by the type of permissions you selected for your app. You will first need to select the permissions you would like your app to have, and then you can subscribe your app to webhook events that are related to that set of permissions. Para más información, consulte "Elección de permisos para una aplicación de GitHub".
Por ejemplo, si deseas que la aplicación reciba una carga de eventos de webhook cada vez que se abra una incidencia nueva en el repositorio, primero tendrás que conceder permiso a la aplicación para acceder a "Incidencias" en "Permisos de repositorio". A continuación, en "Suscribirse a eventos", puede seleccionar "Problemas".
Para obtener más información sobre los permisos necesarios para cada evento de webhook, consulta "Eventos y cargas de webhook".