Solución de problemas de webhooks

Faltan entregas de webhooks

Si no recibe las entregas de webhook que espera, debe identificar el punto en el que falta la entrega.

1. Desencadene un evento que espera generar una entrega de webhook. Por ejemplo, si su webhook es un webhook de repositorio que está suscrito al evento issues, puede abrir una incidencia en ese repositorio.

2. Examine el registro de entregas recientes del webhook. Para obtener información sobre cómo hacerlo para cada tipo de webhook, consulta Visualizar las entregas de los webhooks.

   Si el registro de entregas recientes no incluye una entrega que corresponde al evento de webhook que desencadenó en el paso anterior, GitHub no intentó realizar una entrega. Para identificar la causa:

   1. Espere unos minutos y compruebe otra vez. Las entregas de webhook pueden tardar unos minutos en aparecer.

   2. Asegúrese de que desencadenó un evento en la ubicación donde está configurado el webhook. Por ejemplo, si el webhook es un webhook de repositorio, asegúrese de que desencadenó el evento en el mismo repositorio donde está configurado el webhook.

   3. Asegúrese de que el webhook está suscrito al evento que desencadenó. Por ejemplo, si espera una entrega de webhook al abrir un problema, asegúrese de que el webhook está suscrito al evento issues.

   4. Asegúrese de que el webhook está activo. Para más información, consulta Desactivación de webhooks.

   5. Asegúrese de que el webhook no se ve afectado por OAuth app. Si su webhook fue creado por un OAuth app en nombre de un usuario que autorizó el OAuth app, el webhook se desactivará automáticamente si se trata de un webhook de organización o de repositorio para una organización que tiene acceso restringido por el OAuth app. Para más información, consulta Acerca de las restricciones de acceso a aplicaciones OAuth en la documentación de GitHub Free.

   6. Compruebe si el evento puede haber alcanzado un límite documentado. Por ejemplo, si inserta más de tres etiquetas a la vez, el evento push no se desencadenará para esa inserción. Para más información sobre los límites documentados para cada evento, consulta Eventos y cargas de webhook.

   7. Compruebe el estado de los webhooks en githubstatus.com.

   Si el registro de entregas recientes indica que se produjo un error con la entrega, GitHub intentó la entrega, pero la entrega no se realizó correctamente. Esto suele deberse a un problema con el servidor. Puede consultar las secciones siguientes para ayudar a resolver el error específico.

3. Examine los registros del servidor. La información de los registros depende del código que ejecuta el servidor para controlar las entregas de webhook. Para ayudarle a diagnosticar problemas en el servidor, puede agregar instrucciones de registro adicionales al código.

No puedes tener más de 250 webhooks

Puedes crear hasta 250 webhooks de repositorio, organización o repositorio para cada tipo de evento. Si intentas crear más, recibirás un error que indica que no puedes tener más de 250 webhooks.

Si necesitas más de 250 webhooks, puedes ejecutar un proxy que reciba webhooks de GitHub y los reenvíe a un número ilimitado de direcciones URL de destino.

No se admite el host de dirección URL localhost

No puede usar localhost ni 127.0.0.1 como una dirección URL de webhook.

Si deseas entregar webhooks al servidor local para realizar pruebas, puedes usar un servicio de reenvío de webhook. Para obtener más información, consulta Prueba de webhooks o visita https://smee.io/.

Fallo al conectar con el host

El failed to connect to host error se produce cuando GitHub intenta una entrega de webhook, pero no pudo resolver la dirección URL del webhook en una dirección IP o hay restricciones de red que impiden la conexión al host.

Para comprobar si un nombre de host se resuelve en una dirección IP, puede usar nslookup. Por ejemplo, si la dirección URL de carga es https://octodex.github.com/webhooks, puede ejecutar nslookup octodex.github.com. Si no se pudo resolver el nombre de host en una dirección IP, el comando nslookup indicará que el servidor no encuentra el nombre de host.

Debe asegurarse de que su servidor permite conexiones desde las direcciones IP de GitHub. Puedes usar el punto de conexión GET /meta para buscar la lista actual de GitHub direcciones IP. Para más información, consulta Puntos de conexión de la API de REST para metadatos. GitHub ocasionalmente realiza cambios en sus direcciones IP, por lo que debes actualizar la lista de direcciones IP permitidas periódicamente.

No se pudo conectar a la red

El error failed to connect to network indica que el servidor rechazó la conexión cuando GitHub intentó entregar un webhook.

Debe asegurarse de que su servidor permite conexiones desde las direcciones IP de GitHub. Puedes usar el punto de conexión GET /meta para buscar la lista actual de GitHub direcciones IP. Para más información, consulta Puntos de conexión de la API de REST para metadatos. GitHub ocasionalmente realiza cambios en sus direcciones IP, por lo que debes actualizar la lista de direcciones IP permitidas periódicamente.

Tiempo de espera agotado

El error timed out indica que GitHub no recibió una respuesta de su servidor en los 30 segundos siguientes a la entrega de un webhook.

El servidor debe responder con una respuesta 2xx dentro de 30 segundos tras recibir una entrega de webhook. Si el servidor tarda más de eso en responder, GitHub finaliza la conexión y considera la entrega fallida.

Para responder a tiempo, es posible que desees configurar una cola para procesar cargas de webhook de forma asincrónica. El servidor puede responder cuando recibe el webhook y, a continuación, procesar la carga en segundo plano sin bloquear futuras entregas de webhook. Por ejemplo, puedes usar servicios como Hookdeck o bibliotecas como Resque (Ruby), RQ (Python) o RabbitMQ.

El certificado de pares no puede autenticarse con los certificados de CA dados

Este error indica que hay un problema relacionado con los certificados del servidor. Los problemas más comunes son:

• El servidor usa un certificado autofirmado.
• El servidor no envía la cadena de certificados completa cuando se establece la conexión.

Para ayudar a diagnosticar el problema, puede usar la prueba del servidor SSL de SSL Labs. Este servicio solo puede trabajar con el puerto predeterminado para HTTPS (puerto 443) y solo puede trabajar con servidores accesibles desde Internet.

También puede usar openssl para ayudar a diagnosticar el problema. Para ello, ejecute openssl s_client -connect HOST:PORT en un terminal. Reemplace HOST por el nombre de host del servidor y PORT por el puerto. Por ejemplo, openssl s_client -connect example.com:443. Para identificar problemas, busque verify error en la salida.

Respuesta HTTP no válida

El error invalid HTTP response se produce cuando el servidor devuelve un estado 4xx o 5xx en respuesta a una entrega de webhook desde GitHub.

Debe configurar el servidor para que devuelva un estado 2xx. Si el servidor devuelve un estado 4xx o 5xx, GitHub registrará la entrega como un error.

Las entregas de webhooks no están ordenadas

GitHub puede entregar webhooks en un orden diferente al orden en que se produjeron los eventos. Si necesita saber cuándo se produjo el evento en relación con otro evento, debe usar las marcas de tiempo incluidas en la carga de entrega.

Las entregas de webhook no son inmediatas

Las entregas de webhook pueden tardar unos minutos en entregarse y aparecer en el registro de entregas recientes. Antes de concluir que se produjo un error en la entrega del webhook, espere unos minutos y vuelva a comprobarlo.

Error en la verificación de la firma

Debe utilizar un secreto de webhook y el encabezado X-Hub-Signature-256 para verificar que la entrega de un webhook procede de GitHub. Para más información, consulta Validación de entregas de webhook.

Si está seguro de que la carga procede de GitHub pero se produce un error en la comprobación de la firma:

• Asegúrese de que ha configurado un secreto para el webhook. El encabezado X-Hub-Signature-256 no estará presente si no ha configurado un secreto para el webhook. Para más información sobre cómo configurar un secreto para el webhook, consulta Editar los webhooks.
• Asegúrese de que usa el encabezado correcto. GitHub recomienda usar el encabezado X-Hub-Signature-256, que utiliza el algoritmo HMAC-SHA256. El encabezado X-Hub-Signature usa el algoritmo HMAC-SHA1 y solo se incluye con fines de herencia.
• Asegúrese de que usa el algoritmo correcto. Si usa el encabezado X-Hub-Signature-256, debe usar el algoritmo HMAC-SHA256.
• Asegúrese de que usa el secreto de webhook correcto. Si no conoce el valor del secreto de webhook, puede actualizar el secreto del webhook. Para más información, consulta Editar los webhooks.
• Asegúrese de que la carga y los encabezados no se modifiquen antes de la comprobación. Por ejemplo, si usa un proxy o un equilibrador de carga, asegúrese de que el proxy o el equilibrador de carga no modifiquen la carga o los encabezados.
• Si tu implementación de idioma y servidor especifican un cifrado de caracteres, asegúrate de que estés manejando la carga útil como UTF-8. Las cargas de webhook pueden contener caracteres Unicode.