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. Para ver un tutorial que muestra cómo usar webhooks con una GitHub App, consulta Creación de una aplicación de GitHub que responda a eventos de webhook.
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 instancia de GitHub App, debes habilitar los webhooks para el registro de GitHub App y especificar una dirección URL de webhook donde GitHub envíe las cargas de webhook.
Si tu instancia de GitHub App no necesita responder a webhooks o solo se va a usar para la autenticación, puedes desactivar la función de webhook en el registro de tu instancia de GitHub App. No es necesario especificar una dirección URL de webhook.
Para más información sobre el registro de una instancia de GitHub App, consulta Registro de una instancia de GitHub App. Para más información sobre cómo cambiar los webhooks a los que suscribe el registro de una instancia de GitHub App, consulta Modificación del registro de una instancia de GitHub App.
Elección de una dirección URL de webhook
Al activar webhooks en el registro de tu instancia de 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 instancia de GitHub App, especifica el dominio único de Smee en el campo "URL de webhook" en la página de registro de GitHub App. Para más información, consulta Registro de una instancia de GitHub App y Modificación del registro de una instancia de 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 instancia de GitHub App, escribe un token secreto en "Secreto de webhook" en la página de registro de GitHub App. Debes elegir una cadena aleatoria de texto con alta entropía. Para más información, consulta Registro de una instancia de GitHub App y Modificación del registro de una instancia de 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 más información, consulta Validación de entregas de webhook.
Suscripción a eventos de webhook
Puedes suscribir tu GitHub App para recibir cargas de webhook para eventos específicos. Los eventos de webhook específicos que puede seleccionar en el registro de la GitHub App vienen determinados por el tipo de permisos que has seleccionado para la aplicación. En primer lugar, deberás seleccionar los permisos que deseas que tenga la aplicación y, a continuación, puedes suscribir la aplicación a eventos de webhook relacionados con ese conjunto de permisos. Para más información, consulta 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.