Solução de problemas de webhooks

Entregas do webhook não recebidas

Se você não estiver recebendo as entregas do webhook esperadas, tente identificar em ponto a entrega está faltando.

1. Dispare um evento que deve resultar em uma entrega de webhook. Por exemplo, se você criou um webhook de repositório que está inscrito no evento issues, poderá abrir um problema nesse repositório.

2. Confira o log entregas recentes do webhook. Para obter informações sobre como fazer isso para cada tipo de webhook, veja "Visualizar entregas do webhook".

   Se o log de entregas recentes não incluir uma entrega que corresponda ao evento do webhook que você disparou na etapa anterior, o GitHub não tentou fazer uma entrega. Para identificar a causa:

   1. Aguarde alguns minutos e cheque novamente. As entregas do webhook podem levar alguns minutos para aparecer.

   2. Verifique se você disparou um evento no local em que o webhook está configurado. Por exemplo, se o webhook for um webhook de repositório, certifique-se de que disparou o evento no mesmo repositório em que o webhook está configurado.

   3. Confira se o webhook está inscrito no evento que você disparou. Por exemplo, se você esperar uma entrega de webhook ao abrir um problema, confira se o webhook está inscrito no evento issues.

   4. Confira se seu webhook está ativo. Para obter mais informações, confira "Desabilitar webhooks".

   5. Veja se webhook não está sendo afetado por restrições de acesso do OAuth app. Se o webhook foi criado por um OAuth app em nome de um usuário que autorizou o OAuth app, o webhook será automaticamente desabilitado se for um webhook de organização ou de repositório para uma organização com acesso restrito pelo OAuth app. Para obter mais informações, veja "Sobre as restrições de acesso do aplicativo OAuth" na documentação do GitHub Free

   6. Cheque se o evento pode ter atingido um limite documentado. Por exemplo, se você efetuar push de mais de três tags ao mesmo tempo, o evento push não será disparado para esse push. Para obter mais informações sobre os limites documentados, veja "Eventos e cargas de webhook".

   7. Cheque o status dos webhooks em githubstatus.com.

   Se o log de entregas recentes indicar que houve um erro na entrega, o GitHub tentou fazer a entrega, mas ela não foi bem-sucedida. Isso geralmente ocorre devido a um problema no servidor. Você pode consultar as seções abaixo para ajudar a resolver o erro específico.

3. Confira os logs do servidor. As informações nos logs dependem do código que o servidor executa para lidar com entregas de webhooks. Para ajudar a diagnosticar problemas no servidor, você pode adicionar instruções de log adicionais ao código.

Não se pode ter mais de 250 webhooks

Você pode criar até 250 webhooks de repositório, organização ou globais para cada tipo de evento. Se tentar criar mais, você receberá um erro informando que não pode ter mais de 250 webhooks.

Se você precisar de mais de 250 webhooks, poderá executar um proxy que receba webhooks de GitHub e os encaminhar para um número ilimitado de URLs de destino.

Não há suporte para localhost de host de URL

Você não pode usar localhost ou 127.0.0.1 como uma URL de webhook.

Se quiser entregar webhooks ao servidor local para teste, você poderá usar um serviço de encaminhamento de webhook. Para obter mais informações, confira "Testar webhooks" ou acesse https://smee.io/.

Falha ao conectar com o host

O erro failed to connect to host ocorre quando o GitHub tenta uma entrega de webhook, mas não consegue resolver a URL do webhook para um endereço IP.

Para verificar se um nome de host é resolvido para um endereço IP, você pode usar nslookup. Por exemplo, se a URL de conteúdo for https://octodex.github.com/webhooks, você poderá executar nslookup octodex.github.com. Se o nome do host não puder ser resolvido para um endereço IP, o comando nslookup indicará que o servidor não pode encontrar o nome do host.

Falha ao conectar à rede

O erro failed to connect to network indica que o servidor recusou a conexão quando o GitHub.com tentou entregar um webhook.

Confira se o servidor permite conexões de endereços IP do GitHub. Você pode usar o ponto de extremidade GET /meta para encontrar a lista atual de endereços IP do GitHub. Para obter mais informações, confira "Pontos de extremidade da API REST para metadados". O GitHub ocasionalmente faz alterações nos seus endereços IP. Portanto, você deve atualizar sua lista de IP permitidos periodicamente.

Tempo limite atingido

O erro timed out indica que o GitHub não recebeu uma resposta do servidor dentro de 30 segundos após a entrega de um webhook.

Seu servidor deve dar uma resposta 2xx em até 30 segundos depois de receber uma entrega de webhook. Se o servidor demorar mais do que isso para responder, o GitHub terminará a conexão e considerará que houve falha na entrega.

Para responder em tempo hábil, convém configurar uma fila para processar conteúdo de webhook de forma assíncrona. Seu servidor pode responder ao receber o webhook e, em seguida, processar o conteúdo em segundo plano sem bloquear futuras entregas de webhook. Por exemplo, você pode usar serviços, como Hookdeck, ou bibliotecas, como Resque (Ruby), RQ (Python) ou RabbitMQ.

O certificado de par não pode ser autenticado com os certificados de Autoridade de Certificação fornecidos

Esse erro indica que há um problema relacionado aos certificados do servidor. Os problemas mais comuns são:

• O servidor está usando um certificado autoassinado.
• O servidor não está enviando a cadeia de certificados completa quando a conexão é estabelecida.

Para ajudar a diagnosticar o problema, você pode usar o teste de servidor SSL da SSL Labs. Esse serviço só pode funcionar com a porta padrão para HTTPS (porta 443) e com servidores que possam ser acessados pela Internet.

Você também pode usar openssl para ajudar a diagnosticar o problema. Para isso, execute openssl s_client -connect HOST:PORT em um terminal. Substitua HOST pelo nome do host do servidor e PORT pela porta. Por exemplo, openssl s_client -connect example.com:443. Para identificar os problemas, procure verify error na saída.

Resposta HTTP inválida

O erro invalid HTTP response ocorre quando o servidor retorna um status 4xx ou 5xx em resposta a uma entrega de webhook do GitHub.

Você deve configurar o servidor para retornar um status 2xx. Se o servidor retornar um status 4xx ou 5xx, o GitHub registrará a entrega como falha.

As entregas de webhooks estão fora de ordem

O GitHub pode entregar webhooks em uma ordem diferente da ordem em que os eventos ocorreram. Se você precisar saber quando o evento ocorreu em relação a outro, use os carimbos de data/hora incluídos no conteúdo da entrega.

As entregas do webhook não são imediatas

As entregas do webhook podem levar alguns minutos para chegar e aparecer no log de entregas recentes. Antes de concluir que a entrega de webhook falhou, aguarde alguns minutos e cheque novamente.

Falha na verificação da assinatura

Você deve usar um segredo de webhook e o cabeçalho X-Hub-Signature-256 para verificar se uma entrega de webhook é de GitHub. Para obter mais informações, confira "Validação de entregas de webhooks".

If you are sure that the payload is from GitHub but the signature verification fails:

• Make sure that you have configured a secret for your webhook. The X-Hub-Signature-256 header will not be present if you have not configured a secret for your webhook. For more information about configuring a secret for your webhook, see "Editando webhooks."
• Make sure you are using the correct header. GitHub recommends that you use the X-Hub-Signature-256 header, which uses the HMAC-SHA256 algorithm. The X-Hub-Signature header uses the HMAC-SHA1 algorithm and is only included for legacy purposes.
• Make sure that you are using the correct algorithm. If you are using the X-Hub-Signature-256 header, you should use the HMAC-SHA256 algorithm.
• Make sure you are using the correct webhook secret. If you don't know the value of your webhook secret, you can update your webhook's secret. For more information, see "Editando webhooks."
• Make sure that the payload and headers are not modified before verification. For example, if you use a proxy or load balancer, make sure that the proxy or load balancer does not modify the payload or headers.
• If your language and server implementation specifies a character encoding, ensure that you handle the payload as UTF-8. Webhook payloads can contain unicode characters.