Eventos y cargas de webhook

Sobre eventos y cargas de webhook

Puedes crear webhooks que se suscriban a los eventos listados en esta página. Para limitar el número de solicitudes HTTP al servidor, solo debes suscribirte a los eventos específicos que planees controlar. Para más información, consulta Crear webhooks.

Cada evento webhook en esta página incluye una descripción de las propiedades del webhook para ese evento. Si el evento tiene varias acciones, se incluyen las propiedades correspondientes a cada acción.

Cada evento solo está disponible para tipos específicos de webhooks. Por ejemplo, un webhook de organización puede suscribirse al evento team, pero un webhook de repositorio no puede. La descripción de cada evento de webhook enumera la disponibilidad de ese evento. Para más información, consulta Tipos de webhooks.

La propiedad sender

La mayoría de las cargas de webhook incluyen una sender propiedad que identifica al usuario que desencadenó el evento. A veces, GitHub no puede identificar a un usuario específico, por ejemplo, cuando un evento proviene de un proceso interno en lugar de una persona, o cuando la acción que lo desencadena no tiene asociado ningún usuario. Para algunos eventos, como check_run y check_suite, esto incluye acciones sin un push de Git ni un actor de API autenticado.

En estos casos, sender se rellena con el usuario ghost, una cuenta de marcador de posición cuya login es ghost y cuyo id no está vinculado a ningún usuario real vigente. No asuma que sender siempre identifica a la persona que causó un evento, y tenga en cuenta al usuario ghost en cualquier lógica de negocio o de seguridad que dependa de ello.

Límite de carga útil

Las cargas se limitan a 25 MB. Si un evento genera una carga mayor, GitHub no entregará una carga para ese evento de webhook. 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.

Encabezados de entrega

Las cargas útiles de HTTP POST que se entregan a la terminal URL configurada para tu webhook contendrán varios encabezados especiales:

• X-GitHub-Hook-ID: identificador único del webhook.
• X-GitHub-Event: nombre del evento que desencadenó la entrega.
• X-GitHub-Delivery: un identificador único global (GUID) para identificar el evento.
• X-Hub-Signature: este encabezado se envía si el webhook está configurado con secret. Este es el resumen hexadecimal de HMAC para el cuerpo de la solicitud y se genera mediante la función de hash SHA-1 y secret como key de HMAC. X-Hub-Signature se proporciona para la compatibilidad con las integraciones existentes. Se recomienda usar la función X-Hub-Signature-256 más segura en su lugar.
• X-Hub-Signature-256: este encabezado se envía si el webhook está configurado con secret. Este es el resumen hexadecimal de HMAC para el cuerpo de la solicitud y se genera mediante la función de hash SHA-256 y secret como key de HMAC. Para más información, consulta Validación de entregas de webhook.
• User-Agent: este encabezado siempre tendrá el prefijo GitHub-Hookshot/.
• X-GitHub-Hook-Installation-Target-Type: tipo de recurso donde se creó el webhook.
• X-GitHub-Hook-Installation-Target-ID: identificador único del recurso donde se creó el webhook.

Para ver el aspecto de cada encabezado en una carga de webhook, consulte Entrega de webhook de ejemplo.

Ejemplo de entrega de webhook

Puede elegir que las cargas se entreguen en formato JSON (application/json) o como datos con codificación URL (x-www-form-urlencoded). A continuación se muestra un ejemplo de una solicitud POST de webhook que usa el formato JSON.

> POST /payload HTTP/1.1

> X-GitHub-Delivery: 72d3162e-cc78-11e3-81ab-4c9367dc0958
> X-Hub-Signature: sha1=7d38cdd689735b008b3c702edd92eea23791c5f6
> X-Hub-Signature-256: sha256=d57c68ca6f92289e6987922ff26938930f6e66a2d161ef06abdf1859230aa23c
> User-Agent: GitHub-Hookshot/044aadd
> Content-Type: application/json
> Content-Length: 6615
> X-GitHub-Event: issues
> X-GitHub-Hook-ID: 292430182
> X-GitHub-Hook-Installation-Target-ID: 79929171
> X-GitHub-Hook-Installation-Target-Type: repository

> {
>   "action": "opened",
>   "issue": {
>     "url": "https://api.github.com/repos/octocat/Hello-World/issues/1347",
>     "number": 1347,
>     ...
>   },
>   "repository" : {
>     "id": 1296269,
>     "full_name": "octocat/Hello-World",
>     "owner": {
>       "login": "octocat",
>       "id": 1,
>       ...
>     },
>     ...
>   },
>   "sender": {
>     "login": "octocat",
>     "id": 1,
>     ...
>   }
> }