Testar webhooks do GitHub em local: guia completo

O teste de webhooks do GitHub em local permite receber eventos de push, pull request, issue e workflow na sua máquina sem fazer deploy para staging. Suba um túnel localhost, registre a URL HTTPS nos ajustes da sua GitHub App ou repositório e depure handlers com verificação de assinatura completa.

Por que webhooks do GitHub precisam de um endpoint público

O GitHub entrega eventos de webhook como requisições HTTP POST a uma URL configurada. A sua máquina local em 127.0.0.1 não é alcançável pelos servidores do GitHub. Um túnel localhost fornece o endpoint HTTPS público que o GitHub exige.

GitHub Apps vs webhooks de repositório

Webhooks de repositório

Configurados por repositório em Settings → Webhooks. Bons para testar os handlers de eventos de um único repo durante o desenvolvimento de uma funcionalidade.

Webhooks de GitHub App

Configurados em nível de app nos ajustes da sua GitHub App. Necessários ao construir integrações que servem vários repositórios ou organizações.

Os dois tipos de entrega usam verificação de assinatura HMAC-SHA256 via o cabeçalho X-Hub-Signature-256.

Passo a passo: teste de webhooks do GitHub em local

1. Inicie a sua app local com um endpoint de webhook (por exemplo /api/webhooks/github).
2. Rode npx portpreview 3000 para obter uma URL HTTPS pública.
3. No GitHub, adicione a URL do túnel mais o caminho do webhook como payload URL.
4. Defina o content type como application/json e selecione os eventos a receber.
5. Gere um segredo de webhook e guarde-o nas suas variáveis de ambiente locais.
6. Dispare eventos (faça push de um commit, abra um PR, crie um issue) e inspecione as entregas.
7. Verifique se o seu handler valida a assinatura e devolve uma resposta 2xx em menos de 10 segundos.

Verificar assinaturas de webhooks do GitHub em local

O GitHub assina cada payload com o seu segredo de webhook. O seu handler deve:

• Ler o corpo cru da requisição antes de fazer o parse do JSON.
• Calcular HMAC-SHA256 usando o seu segredo.
• Comparar com o cabeçalho X-Hub-Signature-256 usando comparação de tempo constante.

Ferramentas de túnel que preservam os cabeçalhos originais deixam você testar o caminho de verificação real. Nunca pule as checagens de assinatura durante o desenvolvimento local.

Eventos para testar em local

• push — lógica de disparo de CI, hooks de proteção de branch, pipelines de deploy.
• pull_request — automação de revisão, bots de label, checagens de merge.
• issues — sincronização do tracker de issues, fluxos de atribuição.
• installation — ciclo de vida de instalação/desinstalação da GitHub App.
• workflow_run — automação pós-CI e processamento de artefatos.

Depurar entregas de webhooks do GitHub que falharam

O GitHub repete entregas falhas com backoff exponencial. Falhas comuns em testes locais:

• Timeout do handler (o GitHub espera resposta em 10 segundos).
• Assinatura incompatível por fazer parse do corpo antes da verificação.
• Sessão do túnel expirada enquanto o GitHub repete.
• Filtro de eventos errado — o handler recebe eventos que não processa.

Use o replay de webhooks para re-testar entregas falhas sem fazer push de novos commits.

Teste de webhooks do GitHub vs smee.io

O smee.io é um proxy de webhooks do GitHub popular para desenvolvimento local. Funciona bem para encaminhamento básico, mas falta inspeção de requisições e replay embutidos. O PortPreview combina túnel com captura e replay numa única ferramenta. Para um guia mais amplo de depuração de webhooks, veja como depurar webhooks em local.

Entre na lista de espera do PortPreview para testes de webhooks do GitHub com visibilidade de requisições embutida.