checklist configurar webhook GitHub em Nginx: exemplo real

17 min de leitura  ·  Guia técnico

Como configurar webhook do GitHub em hospedagem Linux com Nginx é o processo de criar um endpoint HTTP seguro no servidor, publicar esse endpoint pelo Nginx e cadastrar a URL no GitHub para receber eventos do repositório. Para configurar um webhook GitHub Nginx funcional, siga estes passos:

1. Prepare o servidor Linux com Nginx, Git, Python 3, curl e acesso SSH administrativo.
2. Crie um usuário de execução e um endpoint local para receber o webhook do GitHub.
3. Configure um segredo compartilhado e valide a assinatura enviada pelo GitHub.
4. Publique o endpoint com Nginx como proxy reverso, sem expor a porta interna da aplicação.
5. Cadastre a URL do webhook no GitHub e teste pelos logs do Nginx e do serviço local.

Pré-requisitos

• Acesso SSH ao servidor Linux com permissão para usar sudo. Se precisar revisar o acesso, veja Acessando servidores VPS Linux da AviraHost.
• Distribuição Linux atual, como Debian 13 ou equivalente, com Nginx 1.28 ou superior disponível nos repositórios do sistema.
• Domínio ou subdomínio apontando para o IP do servidor, por exemplo deploy.seudominio.com.br.
• Repositório Git já clonado no diretório da aplicação, por exemplo /var/www/app.
• Acesso administrativo ao repositório no GitHub para criar o webhook.
• Portas 80 e 443 liberadas para o Nginx. A porta interna do endpoint não deve ficar pública.
• Um segredo longo para validar a assinatura do webhook. Use um valor exclusivo para esse repositório.

Como configurar webhook do GitHub em hospedagem Linux com Nginx

A configuração de webhook GitHub em hospedagem Linux começa pela base do servidor: pacotes instalados, diretórios corretos e um usuário separado para executar o deploy. Na prática, esse isolamento evita que a requisição recebida pelo GitHub rode comandos como root. O Nginx ficará exposto ao público, enquanto o serviço local escutará apenas em 127.0.0.1, reduzindo a superfície de acesso.

Ao rodar os comandos abaixo, você cria a estrutura do webhook, instala dependências comuns e prepara permissões. Ajuste /var/www/app para o diretório real da sua aplicação. Se o projeto ainda não estiver clonado, clone antes com o método de autenticação que você já utiliza, como chave de deploy ou HTTPS autenticado.

sudo apt update
sudo apt install -y nginx git python3 openssl curl

Output esperado:
Reading package lists... Done
Building dependency tree... Done
nginx, git, python3, openssl e curl instalados ou já presentes no sistema

sudo install -d -m 750 /opt/github-webhook /var/www/app
sudo useradd --system --home /opt/github-webhook --shell /usr/sbin/nologin deployhook
sudo chown -R deployhook:deployhook /opt/github-webhook /var/www/app

Output esperado:
sem saída quando os diretórios, o usuário e as permissões são aplicados com sucesso

Se o usuário deployhook já existir, o comando useradd retornará uma mensagem informando que o usuário existe. Nesse caso, não é necessário recriá-lo; siga com o ajuste de permissões. Para confirmar que o Nginx está ativo antes de publicar o webhook, execute:

systemctl status nginx --no-pager

Output esperado:
Active: active running

Criar endpoint para webhook GitHub com validação de assinatura

Um endpoint de webhook GitHub deploy automático não deve confiar apenas no endereço de origem da requisição. A proteção básica é validar a assinatura X-Hub-Signature-256 usando o mesmo segredo configurado no repositório do GitHub. Assim, mesmo que alguém descubra a URL, a chamada será recusada se não tiver a assinatura correta.

O exemplo abaixo usa Python 3 nativo para escutar em 127.0.0.1:9000, validar o HMAC SHA-256 e executar um script de deploy. Ele não expõe uma API complexa, não interpreta comandos recebidos no payload e não usa o corpo da requisição para montar comandos de shell. Esse detalhe é importante: o webhook deve acionar um fluxo conhecido, não executar instruções vindas da internet.

sudo tee /opt/github-webhook/server.py > /dev/null <<'PY'
#!/usr/bin/env python3
from http.server import HTTPServer, BaseHTTPRequestHandler
import hmac
import hashlib
import os
import subprocess

SECRET = os.environ.get("GITHUB_WEBHOOK_SECRET", "")
DEPLOY_SCRIPT = "/opt/github-webhook/deploy.sh"

class Handler(BaseHTTPRequestHandler):
    def do_POST(self):
        length = int(self.headers.get("Content-Length", "0"))
        body = self.rfile.read(length)
        received = self.headers.get("X-Hub-Signature-256", "")
        expected = "sha256=" + hmac.new(SECRET.encode(), body, hashlib.sha256).hexdigest()

        if not SECRET or not hmac.compare_digest(expected, received):
            self.send_response(401)
            self.end_headers()
            self.wfile.write(b"assinatura invalida")
            return

        try:
            subprocess.run(["/bin/bash", DEPLOY_SCRIPT], check=True)
            self.send_response(200)
            self.end_headers()
            self.wfile.write(b"deploy acionado")
        except subprocess.CalledProcessError:
            self.send_response(500)
            self.end_headers()
            self.wfile.write(b"falha no deploy")

HTTPServer(("127.0.0.1", 9000), Handler).serve_forever()
PY
sudo chmod 750 /opt/github-webhook/server.py
sudo chown deployhook:deployhook /opt/github-webhook/server.py

Output esperado:
sem saída quando o arquivo é criado e as permissões são aplicadas

Agora crie o script que será executado após uma assinatura válida. Este exemplo faz git pull com avanço rápido apenas na branch main e grava o resultado em log. Se sua aplicação usa build, cache ou reinício de serviço, inclua esses passos depois do git pull, sempre com comandos previsíveis.

Atenção: comandos de deploy podem sobrescrever arquivos da aplicação. Antes de automatizar, teste manualmente em um ambiente controlado e confirme que o diretório correto está sendo atualizado.

sudo touch /var/log/github-webhook-deploy.log
sudo chown deployhook:deployhook /var/log/github-webhook-deploy.log
sudo tee /opt/github-webhook/deploy.sh > /dev/null <<'SH'
#!/usr/bin/env bash
set -euo pipefail
APP_DIR=/var/www/app
LOG=/var/log/github-webhook-deploy.log
cd $APP_DIR
git pull --ff-only origin main >> $LOG 2>&1
date >> $LOG
SH
sudo chmod 750 /opt/github-webhook/deploy.sh
sudo chown deployhook:deployhook /opt/github-webhook/deploy.sh

Output esperado:
sem saída quando o log e o script são criados com sucesso

Executar o endpoint como serviço local no Linux

Rodar webhook GitHub no Linux como serviço facilita reinicialização automática, auditoria e diagnóstico. Em vez de deixar um processo aberto no terminal, o systemd mantém o endpoint ativo e injeta o segredo pelo ambiente do serviço. Troque o valor de GITHUB_WEBHOOK_SECRET por um segredo longo, diferente da senha do GitHub e diferente de qualquer chave SSH.

sudo tee /etc/systemd/system/github-webhook.service > /dev/null <<'SERVICE'
[Unit]
Description=GitHub webhook receiver
After=network.target

[Service]
Type=simple
User=deployhook
Group=deployhook
Environment=GITHUB_WEBHOOK_SECRET=troque-este-segredo-longo
ExecStart=/usr/bin/python3 /opt/github-webhook/server.py
Restart=on-failure
WorkingDirectory=/opt/github-webhook

[Install]
WantedBy=multi-user.target
SERVICE
sudo systemctl daemon-reload
sudo systemctl enable --now github-webhook

Output esperado:
github-webhook.service habilitado e iniciado sem erro

Verifique se o serviço está escutando somente no endereço local. Esse ponto é essencial em uma configuração de proxy reverso Nginx webhook, porque o mundo externo deve acessar apenas o Nginx, não a porta 9000 diretamente.

systemctl status github-webhook --no-pager
ss -ltnp | grep 9000

Output esperado:
Active: active running
LISTEN 0 5 127.0.0.1:9000

Teste uma chamada sem assinatura. O retorno correto é 401, porque o endpoint está recusando requisições falsas. Ao rodar este comando, você verá que o serviço responde, mas não executa deploy sem validação.

curl -i -X POST http://127.0.0.1:9000/ -d "teste"

Output esperado:
HTTP/1.0 401 Unauthorized
assinatura invalida

Publicar webhook pelo Nginx como proxy reverso

O proxy reverso Nginx para webhook permite receber chamadas públicas em HTTP ou HTTPS e encaminhar a requisição para o serviço local. O ideal é usar HTTPS no domínio do webhook, principalmente porque o segredo protege a assinatura, mas o tráfego também deve ser transportado de forma segura. Se você ainda está ajustando redirecionamento, consulte Como redirecionar um site http para https?.

Edite o arquivo do seu site no Nginx e adicione uma rota exclusiva para o webhook. O exemplo abaixo usa deploy.seudominio.com.br e encaminha apenas /github-webhook para 127.0.0.1:9000. Em ambientes com vários sites, mantenha essa rota no bloco do domínio correto para evitar que qualquer virtual host receba o deploy.

sudo tee /etc/nginx/conf.d/github-webhook.conf > /dev/null <<'NGINX'
server {
    listen 80;
    server_name deploy.seudominio.com.br;

    location = /github-webhook {
        proxy_pass http://127.0.0.1:9000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 30s;
    }
}
NGINX
sudo nginx -t
sudo systemctl reload nginx

Output esperado:
nginx: configuration file /etc/nginx/nginx.conf test is successful
Nginx recarregado sem erro

Depois, teste a URL pública. Sem assinatura, a resposta ainda deve ser 401, o que confirma que o Nginx está encaminhando corretamente e que o endpoint está barrando chamadas não autenticadas.

curl -i -X POST http://deploy.seudominio.com.br/github-webhook -d "teste"

Output esperado:
HTTP/1.0 401 Unauthorized
assinatura invalida

Se você usa firewall, mantenha públicas apenas as portas do Nginx. O endpoint local na porta 9000 não precisa ser exposto. Essa abordagem também facilita migrações, pois você pode trocar a implementação do endpoint sem alterar a URL cadastrada no GitHub.

Cadastrar URL do webhook no GitHub e validar logs

Para cadastrar webhook GitHub com secret, acesse o repositório no GitHub, entre em Settings, depois Webhooks, e crie uma nova entrega. No campo Payload URL, informe a URL pública, como https://deploy.seudominio.com.br/github-webhook. Em Content type, use application/json. No campo Secret, informe exatamente o mesmo valor configurado em GITHUB_WEBHOOK_SECRET no serviço systemd.

1. Abra o repositório no GitHub com uma conta que tenha permissão administrativa.
2. Acesse Settings e depois Webhooks.
3. Clique em Add webhook.
4. Preencha Payload URL com a rota publicada pelo Nginx.
5. Configure Content type como application/json.
6. Informe o Secret igual ao segredo do serviço local.
7. Selecione apenas o evento de push, se o objetivo for deploy automático ao enviar código.
8. Salve e use a área de entregas do webhook para reenviar ou inspecionar a chamada.

Agora acompanhe os logs. Os logs Nginx webhook GitHub mostram se a requisição chegou ao servidor. O log do serviço mostra se a validação e o deploy foram executados. Ao rodar os comandos abaixo logo após um push ou uma entrega manual do GitHub, você verá o caminho da requisição.

sudo tail -n 30 /var/log/nginx/access.log
sudo journalctl -u github-webhook -n 50 --no-pager
sudo tail -n 30 /var/log/github-webhook-deploy.log

Output esperado:
linha de acesso ao caminho /github-webhook no access.log
serviço github-webhook sem erro crítico no journalctl
saída do git pull registrada no log de deploy

Se a entrega aparece como sucesso no GitHub e o log de deploy mostra atualização, o fluxo básico está funcional. Se o GitHub mostra falha, use o código HTTP exibido na entrega: 401 indica assinatura inválida, 404 geralmente indica rota incorreta no Nginx, 500 indica falha no script de deploy.

Problemas comuns e como resolver

Sintoma: GitHub mostra erro 401 na entrega do webhook

Causa: o segredo configurado no GitHub é diferente do valor definido em GITHUB_WEBHOOK_SECRET, ou o serviço não foi reiniciado depois da alteração.

Solução: copie novamente o segredo para o webhook do GitHub e para o arquivo de serviço systemd. Depois rode sudo systemctl daemon-reload e sudo systemctl restart github-webhook. Teste uma nova entrega pelo painel do GitHub e confira o journalctl do serviço.

Sintoma: a requisição chega ao Nginx, mas retorna 502 Bad Gateway

Causa: o Nginx não consegue conectar no serviço local em 127.0.0.1:9000. Normalmente o endpoint está parado, escutando em outra porta ou falhando ao iniciar.

Solução: verifique systemctl status github-webhook --no-pager e ss -ltnp | grep 9000. Se o serviço não estiver ativo, leia sudo journalctl -u github-webhook -n 80 --no-pager, corrija o erro apontado e reinicie o serviço.

Sintoma: o webhook retorna 200, mas o código não atualiza

Causa: o script foi executado, mas o usuário deployhook não tem permissão no diretório da aplicação ou não tem acesso ao repositório remoto.

Solução: rode sudo -u deployhook git -C /var/www/app status e sudo -u deployhook git -C /var/www/app pull --ff-only origin main. Se falhar, ajuste permissões, chave de deploy ou URL remota antes de tentar novamente pelo GitHub.

Sintoma: nada aparece nos logs do Nginx

Causa: o DNS do domínio ainda não aponta para o servidor correto, a URL cadastrada no GitHub está errada ou o firewall bloqueia as portas 80 e 443.

Solução: confirme o registro DNS do subdomínio, teste curl -I http://deploy.seudominio.com.br e valide as regras do firewall. Se o domínio responde em outro servidor, corrija o apontamento antes de repetir a entrega do webhook.

Perguntas frequentes sobre Como configurar webhook do GitHub em hospedagem Linux com Nginx

Como configurar webhook do GitHub em hospedagem Linux com Nginx?

Para configurar um webhook do GitHub em hospedagem Linux com Nginx, crie um endpoint HTTP no servidor, proteja a rota com um segredo compartilhado e faça o Nginx encaminhar a requisição para esse endpoint. Depois, cadastre a URL do webhook no repositório do GitHub e valide o recebimento pelos logs do serviço e do Nginx.

Preciso abrir alguma porta para o webhook do GitHub funcionar no Nginx?

O webhook do GitHub normalmente chega pelas portas HTTP ou HTTPS do site, ou seja, 80 e 443. Se o endpoint estiver atrás do Nginx, não é necessário expor a porta interna da aplicação; o ideal é deixar apenas o Nginx público e encaminhar a requisição via proxy reverso.

Como proteger um webhook do GitHub contra requisições falsas?

A forma básica de proteção é configurar um segredo no GitHub e validar a assinatura recebida no endpoint antes de executar qualquer ação. Também é recomendável limitar o que o script de deploy pode executar, registrar logs e evitar comandos destrutivos sem validação.

O webhook do GitHub pode fazer deploy automático em hospedagem Linux?

Sim, o webhook pode acionar um script de deploy quando houver push em uma branch específica do repositório. O script deve ser executado por um usuário com permissões controladas, atualizar apenas o diretório correto e registrar saída em log para facilitar auditoria.

Como saber se o webhook do GitHub chegou ao servidor Nginx?

Verifique primeiro a aba de entregas do webhook no GitHub e depois os logs de acesso e erro do Nginx no servidor. Se a requisição aparecer no Nginx, mas o deploy não ocorrer, o problema provavelmente está no endpoint, nas permissões do script ou no serviço local que recebe a chamada.

Conclusão

• Publique o webhook apenas pelo Nginx e mantenha o serviço interno preso ao endereço 127.0.0.1.
• Use segredo compartilhado e validação de assinatura antes de executar qualquer script de deploy.
• Audite o fluxo pelos logs do GitHub, do Nginx, do systemd e do script de deploy.

Leia também

• Guia para Configurar Logs Personalizados no Nginx em VPS Linux
• Passo a passo para configurar Nginx com PHP-FPM no VPS Linux: Guia Completo
• Checklist Nginx em produção: 12 verificações antes do deploy

Precisa de ajuda com webhook GitHub em Nginx?

Uma infraestrutura bem configurada reduz falhas de deploy e facilita auditoria quando algo não sai como esperado. A AviraHost oferece ambiente VPS para projetos que precisam de Nginx, Git, automação e controle de servidor.

Conheça os planos de Servidor VPS da AviraHost