Información sobre los webhooks y GitHub Apps
Los webhooks permiten que tu GitHub App reciba notificaciones en tiempo real cuando se producen eventos en GitHub, como cuando alguien envía un commit o abre una solicitud de incorporación de cambios en un repositorio al que tu aplicación tiene acceso. Para obtener más información sobre los webhooks, consulta Acerca de webhooks. Para ver un tutorial en el que se muestra cómo utilizar webhooks con un GitHub App, consulte Creación de una aplicación de GitHub que responda a eventos de webhook.
Puedes configurar tu GitHub App para que reciba webhooks de eventos específicos en GitHub y actúe automáticamente en función de 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 habilitar los webhooks para tu registro en GitHub App y especificar una URL de webhook a la que GitHub enviará las cargas útiles de los webhooks.
Si tu GitHub App no necesita responder a los webhooks o solo se utilizará para la autenticación, puedes desactivar la función de webhooks para tu registro GitHub App. No es necesario especificar una dirección URL de webhook.
Para obtener más información sobre cómo registrar un GitHub App, vea Registro de una aplicación de GitHub. Para obtener más información sobre cómo cambiar los webhooks a los que se suscribe un GitHub App registro, consulte Modificación de un registro de aplicación de GitHub.
Elección de una dirección URL de webhook
Cuando actives los webhooks para tu registro GitHub App, tendrás que especificar una 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 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 webhooks que recibirá tu GitHub App.
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
Puede utilizar Smee para crear un dominio único al que GitHub pueda enviar las cargas útiles de los webhooks, sin exponer su entorno de desarrollo local a Internet. Smee denomina a este dominio único "URL de proxy de webhook". Puede utilizar la URL del proxy de webhooks de Smee como URL de webhook para su 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 URL de webhook de Smee a su GitHub App, introduzca su dominio único de Smee en el campo URL de webhook de la página de registro de su GitHub App. Para más información, consulta Registro de una aplicación de GitHub y Modificación de un registro de aplicación de GitHub.
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 GitHub API.
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, puede usar funciones en la nube como Azure Functions, 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, debe 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 tu aplicación de GitHub, introduce un secreto debajo de «Secreto de webhook» en tu página de registro GitHub App. Debes elegir una cadena aleatoria de texto con alta entropía. Para más información, consulta Registro de una aplicación de GitHub y Modificación de un registro de aplicación de GitHub.
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 útiles 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 obtener 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.