GitScrum / Docs

Solução de Problemas

Diagnostique e corrija problemas comuns de webhooks do GitScrum: falhas de entrega, erros de timeout, problemas de payload e erros de configuração.

Problemas comuns de webhook e como resolvê-los.

Webhook Não Dispara

Endpoint não salvo

Sintoma: Nenhuma requisição chega ao seu servidor após configurar um webhook.

Solução:

  1. Verifique se o indicador de status está verde na configuração do webhook
  2. Reinsira a URL e pressione Enter para salvar
  3. Atualize a página e confirme que a URL persiste

Projeto errado

Sintoma: Webhooks funcionam para um projeto, mas não para outro.

Solução: Webhooks são por projeto. Verifique se você configurou o endpoint nas configurações do projeto correto.

Plano Pro necessário

Sintoma: A configuração de webhook aparece, mas os endpoints não ativam.

Solução: Webhooks requerem um plano Pro ou superior. Verifique o status de faturamento do seu workspace.

Falhas de Entrega

Endpoint retorna status não-2xx

Sintoma: O GitScrum mostra falha de entrega para um webhook.

Solução:

  • Verifique os logs do seu servidor para erros
  • Garanta que seu endpoint retorna um código de status 2xx (200, 201, 202, 204)
  • Verifique se o caminho do endpoint corresponde exatamente

Timeout de conexão

Sintoma: Entregas de webhook falham consistentemente com erros de timeout.

Solução:

  • Retorne 200 imediatamente antes de processar (use processamento baseado em fila)
  • Verifique se seu servidor responde dentro de 30 segundos
  • Verifique se seu servidor não está bloqueado por um firewall

Erros SSL/TLS

Sintoma: Entregas de webhook HTTPS falham.

Solução:

  • Garanta que seu certificado SSL é válido e não está expirado
  • Verifique se a cadeia de certificados está completa
  • Confirme que seu servidor suporta TLS 1.2 ou superior

Problemas de Payload

Payload vazio ou malformado

Sintoma: Seu endpoint recebe a requisição, mas o corpo está vazio ou não pode ser parseado.

Solução:

  • Garanta que seu servidor faz parse do content type application/json
  • Adicione o middleware express.json() (Node.js) ou equivalente
  • Verifique se sua biblioteca de parsing suporta o tamanho do payload
// Express.js - ensure JSON parsing is enabled
app.use(express.json({ limit: '10mb' }));
# Flask - ensure JSON content type is handled
event = request.get_json(force=True)

Estrutura de payload inesperada

Sintoma: Seu código falha porque campos esperados estão ausentes.

Solução:

  • Sempre verifique valores null antes de acessar propriedades aninhadas
  • Use optional chaining em JavaScript: data?.workflow?.title
  • Valide a estrutura do payload antes de processar
  • Consulte Formato do Payload para a referência completa dos campos

Problemas de Teste

Botão de teste envia, mas servidor não recebe

Sintoma: Clicar no botão de teste mostra sucesso, mas nenhuma requisição chega ao seu servidor.

Solução:

  • Verifique se seu servidor é acessível publicamente (não está atrás de VPN ou rede local)
  • Confirme que a URL está correta incluindo o protocolo (https://)
  • Tente usar uma ferramenta de inspeção de requisições como webhook.site para verificar a entrega
  • Se estiver usando ngrok, garanta que o túnel ainda está ativo

Teste funciona, mas eventos reais não disparam

Sintoma: Payloads de teste chegam, mas eventos reais não acionam webhooks.

Solução:

  • Verifique se o evento específico está configurado (teste envia para o endpoint específico)
  • Confirme que a ação que você está realizando corresponde ao tipo de evento
  • Garanta que está realizando a ação no projeto correto

Problemas de Permissão

Não consegue acessar configurações de webhook

Sintoma: A aba Webhooks não está visível ou as configurações são somente leitura.

Solução:

  • Apenas roles Manager e Owner podem configurar webhooks
  • Entre em contato com o gerente do projeto ou owner do workspace para acesso

Dicas de Depuração

Use webhook.site para inspeção

Teste sua configuração de webhook usando webhook.site:

  1. Acesse webhook.site e copie a URL única
  2. Cole-a como endpoint nos webhooks do GitScrum
  3. Dispare um evento ou clique em Test
  4. Inspecione os detalhes completos da requisição no webhook.site

Verifique os logs de entrega

O GitScrum registra cada tentativa de entrega de webhook incluindo:

  • URL do endpoint
  • Corpo do payload
  • Código de status HTTP retornado
  • Timestamp

Revise esses logs para diagnosticar problemas de entrega.

Desenvolvimento local com ngrok

Para testes locais, use ngrok para criar um túnel público:

ngrok http 3000

A URL HTTPS fornecida pelo ngrok pode ser usada como URL do endpoint de webhook. Substitua-a no GitScrum quando a URL do túnel mudar.

Relacionado