Acerca de webhooks
Los webhooks son un método de comunicación que permite a los usuarios suscribirse a eventos que se producen en un sistema de software. Los webhooks se pueden desencadenar siempre que se produzcan eventos específicos en GitHub. Por ejemplo, puedes configurar tus webhooks para ejecutarse siempre que:
- Se inserte código en un repositorio.
- Se abra una solicitud de extracción.
- Se cree un sitio GitHub Pages.
- Se agregue un nuevo miembro a un equipo.
Puedes crear webhooks para para una organización, para un repositorio o para GitHub App.
Puedes crear hasta 20 webhooks para cada evento en cada destino de instalación (instancia, organización específica o repositorio específico de GitHub Enterprise Server).
Para obtener más información sobre la creación de webhooks, consulta "Crear webhooks".
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.
Acerca de los eventos de webhook
Cuando configuras un webhook, puedes elegir qué eventos te enviarán cargas útiles. Para limitar el número de solicitudes HTTP al servidor, solo debes suscribirte a los eventos específicos que planees controlar. Para obtener una lista completa de los eventos de webhook y sus cargas, consulta "Eventos y cargas de webhook".
Algunos eventos de webhook tienen acciones, que son operaciones que se pueden realizar en el recurso que representa el evento de webhook. Si un evento de webhook tiene varios tipos de acción, cada acción desencadenará una entrega de carga. Por ejemplo, el evento de webhook package desencadenará una entrega de carga cuando un paquete esté updated o edited. No puedes suscribirte a acciones individuales de webhook. Al configurar un webhook, recibirás cargas para todas las acciones relacionadas con ese webhook.
De forma predeterminada, los webhooks instalados en GitHub Enterprise, una organización o un repositorio solo se suscriben al evento push. De forma predeterminada, los webhooks de las GitHub Apps no se suscriben a ningún evento. Puedes cambiar los eventos a los que se suscribe un webhook en cualquier momento.
Acerca de las entregas de webhooks
Cuando recibas una entrega de webhook, la carga contendrá el nombre del evento y la acción que desencadenó la entrega, junto con otra información sobre el propio evento. Para obtener más información sobre los encabezados de entrega que se incluyen con cada carga y una entrega de ejemplo, consulta "Eventos y cargas de webhook". Parte de la información se incluye en la mayoría o todas las entregas de webhook, como el usuario que realizó el evento, o la organización o el repositorio donde se produjo el evento.
Cuando crees un webhook, necesitarás especificar una dirección URL donde desees recibir los eventos de webhook. GitHub enviará una carga HTTP POST a esta URL cuando se produzca cualquier evento al que esté suscrito el webhook. Después, el servidor puede procesar y responder al webhook. Para obtener más información, consulta "Identificar las entregas de los webhooks".
Nota: Las cargas se limitan a 25 MB. Si tu evento genera una carga útil mayor, el webhook no se lanzará. Esto puede pasar, por ejemplo, en un evento create si se insertan muchas ramas o etiquetas al mismo tiempo. Te sugerimos monitorear el tamaño de tu carga útil para garantizar la entrega.
Para obtener información sobre cómo ver las entregas de webhook, consulta "Visualizar las entregas de los webhooks".
Cuándo usar webhooks
Los webhooks se pueden usar en una amplia gama de escenarios, entre los que se incluyen:
- Desencadenar canalizaciones de CI (integración continua) en un servidor de CI externo. Por ejemplo, para desencadenar CI en Jenkins o CircleCI cuando el código se inserta en una rama.
- Enviar notificaciones sobre eventos en GitHub a las plataformas de colaboración. Por ejemplo, enviar una notificación a Discord o Slack cuando hay una revisión en una solicitud de incorporación de cambios.
- Actualizar un rastreador de problemas externos como Jira.
- Realizar una implementación en un servidor de producción.
- Registrar eventos a medida que se producen en GitHub, con fines de auditoría.
Los webhooks permiten recibir datos tal como sucede, en lugar de llamar a una API de forma intermitente para ver si los datos están disponibles, lo que se conoce como sondeo de actualizaciones. Solo tienes que expresar interés en un evento una vez, al crear el webhook.
Los webhooks tienen las siguientes ventajas sobre el uso de las API:
- Los webhooks requieren menos esfuerzo y menos recursos que el sondeo de una API.
- Los webhooks escalan mejor que las llamadas a la API. Si necesitas supervisar muchos recursos, llamar a la API para cada recurso puede hacer que alcances rápidamente la cuota del límite de velocidad de API. En su lugar, puedes suscribirte a varios eventos de webhook y recibir información solo cuando se produce un evento.
- Los webhooks permiten actualizaciones casi en tiempo real, ya que los webhooks se desencadenan cuando se produce un evento.
Si solo necesitas información una vez o de manera intermitente, o solo quieres obtener información de un pequeño conjunto de recursos sin planes para escalar verticalmente, puedes llamar a la API cuando necesites la información pertinente.
Para obtener información sobre los procedimientos recomendados que se deben seguir al usar webhooks, consulta "Procedimientos recomendados para usar webhooks".
Acerca de los permisos para administrar webhooks
Para administrar webhooks, debes ser propietario o tener acceso de administrador al recurso en el que se crea el webhook y se escucha eventos. Por ejemplo, para administrar webhooks de la organización, necesitas permisos de administrador para esa organización. Para obtener más información sobre la creación de diferentes tipos de webhooks, consulta "Crear webhooks".
Sustituir GitHub Services por webhooks
GitHub Services (a veces denominado enlaces de servicio) es el método heredado de integración en el que GitHub hospeda una parte de los servicios del integrador desde el repositorio github-services. En 2019, hemos obsoletizado los GitHub Services para favorecer la integración con los webhooks. Para obtener más información sobre esta obsolescencia, consulta esta publicación de blog.