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, confira 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 saber mais, 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, confira Sobre as restrições de acesso do aplicativo OAuth.

   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 para cada evento, confira 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 20 webhooks

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

Se você precisar de mais de 20 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 visite 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 saber mais, 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 10 segundos após a entrega de um webhook.

Seu servidor deve dar uma resposta 2xx em até 10 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.

Se sua conta tiver um aumento nas entregas de webhook, o GitHub pode limitar temporariamente a taxa de entregas para a sua conta. Se suas entregas de webhook forem reduzidas pelo GitHub, a propriedade throttled_at de cada entrega afetada mostrará o carimbo de data/hora de quando a entrega foi limitada. Você pode verificar isso usando a API REST, confira Listar as entregas de lista para um webhook de repositório.

Para evitar atrasos, assine apenas os eventos de webhook necessários para sua conta, reduzindo a frequência de entregas. Consulte "Melhores práticas para usar webhooks".

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 saber mais, confira Validação de entregas de webhooks.

Se você tiver certeza de que a carga é da GitHub, mas a verificação da assinatura falhar:

• Certifique-se de ter configurado um segredo para seu webhook. O cabeçalho X-Hub-Signature-256 não estará presente se você não tiver configurado um segredo para seu webhook. Para obter mais informações sobre como configurar um segredo para seu webhook, consulte "Editando webhooks".
• Certifique-se de que esteja usando o cabeçalho correto. A GitHub recomenda que você use o cabeçalho X-Hub-Signature-256, que usa o algoritmo HMAC-SHA256. O cabeçalho X-Hub-Signature usa o algoritmo HMAC-SHA1 e é incluído apenas para fins herdados.
• Certifique-se de que esteja usando o algoritmo correto. Se estiver usando o cabeçalho X-Hub-Signature-256, deverá usar o algoritmo HMAC-SHA256.
• Verifique se você está usando o segredo correto do webhook. Se você não souber o valor do segredo do webhook, poderá atualizar o segredo do webhook. Para obter mais informações, confira "Editando webhooks".
• Certifique-se de que a carga útil e os cabeçalhos não sejam modificados antes da verificação. Por exemplo, se você usar um proxy ou um balanceador de carga, certifique-se de que o proxy ou o balanceador de carga não modifique a carga útil ou os cabeçalhos.
• Se o seu idioma e a implementação de servidor especificarem uma codificação de caracteres, certifique-se de que você manipula a carga como UTF-8. As cargas do webhook podem conter caracteres unicode.