Implementar assinatura HMAC e SSL em endpoints webhook Nginx é publicar a URL só em HTTPS, com certificado válido no hostname, e recusar o evento se o HMAC do corpo bruto não bater com o segredo. O Nginx encerra o TLS e encaminha a requisição; ele não calcula a assinatura sozinho. Para deixar o endpoint pronto, siga estes passos:
- Aponte o hostname do webhook para o servidor e emita o certificado com cadeia completa.
- Publique o location só na porta 443, aceitando POST e limitando o tamanho do corpo.
- Encaminhe o corpo intacto para um serviço em 127.0.0.1 que guarda o segredo.
- Calcule HMAC-SHA256 sobre os bytes recebidos e compare em tempo constante.
- Teste o handshake TLS, uma assinatura válida e uma assinatura alterada antes de cadastrar a URL no provedor.
Pré-requisitos
O certificado TLS e o segredo compartilhado precisam existir antes de qualquer cadastro no provedor. Sem os dois, o endpoint ou falha no handshake ou aceita evento de quem não deveria.
- Ubuntu 24.04 LTS com Nginx 1.28 ou mais novo. Confira com
nginx -v. A saída começa comnginx version: nginx/1.28. Se a linha mostrar 1.24 ou outra série anterior, pare e instale a 1.28 pelo repositório oficial do Nginx antes de copiar a configuração abaixo. A diretivahttp2 on;não existe nas séries antigas. - Python 3 do sistema (
/usr/bin/python3), OpenSSL 3 e o pacotecertbotse o certificado ainda não existir. - Um hostname só do webhook, neste artigo
hooks.seudominio.com.br, com DNS apontando para o IP público deste servidor. Não use o IP cru na URL: o nome do certificado não vai coincidir. - A porta 80 liberada na hora de emitir o certificado e a 443 liberada em definitivo. A porta do validador (8080) fica só em localhost.
- Acesso root por SSH e um segredo que o provedor também receberá. Esse valor não entra no Git, na configuração do Nginx nem no access_log.
- A documentação do provedor com o nome do cabeçalho, o algoritmo e a codificação (hex ou base64). O exemplo daqui usa
X-Webhook-Signature: sha256=mais o hex do HMAC-SHA256 do corpo bruto. GitHub, por exemplo, usa outro nome de cabeçalho; o princípio é o mesmo, o contrato não.
Implementar assinatura HMAC e SSL em endpoints webhook Nginx
O proxy reverso deste endpoint faz três coisas e só três: apresenta o certificado, recusa método e tamanho fora do combinado e entrega os mesmos bytes do corpo ao processo que conhece o segredo. Quem prova a origem do evento é o HMAC. Quem prova o servidor e protege o caminho é o TLS. Tratar os dois como a mesma trava é o erro que faz webhook "HTTPS" aceitar payload forjado de qualquer cliente que alcance a URL.
A ordem importa. Primeiro o hostname resolve e o certificado cobre esse nome, com a cadeia completa. Depois o Nginx sobe o server na 443 e um location exato. Por último entra o serviço local, que lê o corpo como chegou, calcula o HMAC e só então executa a regra de negócio. Se você inverter e cadastrar a URL no provedor antes do teste de assinatura inválida, o provedor pode marcar o endpoint como saudável só porque recebeu HTTP 200 de uma página genérica.
Neste desenho o Nginx escuta na rede e o Python escuta em 127.0.0.1:8080. O segredo fica em arquivo legível só pelo usuário do serviço. O Nginx nunca vê esse arquivo. Não há módulo estável, igual em toda instalação 1.28, que substitua essa conferência sem código seu. Dá para fazer a conta em njs, mas a API muda entre versões e o corpo precisa ser lido por inteiro; o serviço local deixa o comportamento visível no journalctl e no código que você versiona sem o segredo.
HTTPS sozinho não impede replay: quem capturar uma requisição válida pode reenviá-la. Se o provedor assina também um timestamp ou um id de evento, a string assinada tem de ser exatamente a que ele definiu, e o id já visto tem de ser descartado pela aplicação. O exemplo abaixo assina só o corpo, que é o contrato mais comum. Não invente um prefixo timestamp.corpo se o provedor não assina isso: a conta nunca fecha.
Se o provedor oferecer certificado de cliente, isso é outra camada. O passo a passo está em Passo a passo: Nginx Reverse Proxy com autenticação mútua TLS. mTLS não calcula HMAC e não substitui o segredo quando o provedor assina o payload.
Certificado e hostname do endpoint
A cadeia de certificados precisa chegar inteira ao cliente do provedor. Arquivo cert.pem sem intermediários é o caso clássico de "funciona no navegador que já tem cache e falha no webhook". Use fullchain.pem em ssl_certificate e a chave privada só em ssl_certificate_key. O master do Nginx lê a chave como root na subida; não abra a chave para o usuário do site e não use chmod 777.
Confirme o DNS antes de emitir qualquer coisa. Os comandos abaixo devem devolver o IP deste servidor. Verifique os dois tipos de registro: um AAAA antigo ou apontando para outro servidor pode fazer o provedor conectar por IPv6 e receber outro certificado ou falhar mesmo que o A esteja correto.
dig +short hooks.seudominio.com.br A
dig +short hooks.seudominio.com.br AAAA
Remova o AAAA indevido ou configure Nginx, firewall e certificado também no endereço IPv6 se ele existir.
No Ubuntu 24.04, instale o cliente do Let's Encrypt e peça o certificado com o plugin do Nginx. A porta 80 precisa responder neste host durante a emissão.
sudo apt-get update
sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot certonly --nginx -d hooks.seudominio.com.br
Ao terminar, os caminhos estáveis são /etc/letsencrypt/live/hooks.seudominio.com.br/fullchain.pem e privkey.pem. São links para archive/. Não copie a chave para outro diretório "para o Nginx achar". Como foi usado certonly, o Certbot não grava bloco server definitivo na configuração; se você já rodou certbot --nginx sem certonly em outro momento, verifique se existe um bloco server duplicado para o mesmo server_name e remova-o antes do reload.
Crie o virtual host em /etc/nginx/conf.d/webhook.conf. Esse diretório entra no contexto http tanto no pacote do Ubuntu quanto no pacote do nginx.org. Adicione o listener IPv6 apenas se houver registro AAAA correto e conectividade IPv6, validando com nginx -t e ss -ltn. Se a pilha IPv6 estiver desabilitada no kernel (net.ipv6.conf.all.disable_ipv6=1), omita a linha listen [::]:443.
server {
listen 80;
server_name hooks.seudominio.com.br;
return 301 https://hooks.seudominio.com.br$request_uri;
}
server {
listen 443 ssl;
http2 on;
server_name hooks.seudominio.com.br;
ssl_certificate /etc/letsencrypt/live/hooks.seudominio.com.br/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/hooks.seudominio.com.br/privkey.pem;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_session_timeout 1d;
ssl_session_cache shared:SSL:10m;
ssl_session_tickets off;
server_tokens off;
location = /webhook {
limit_except POST { deny all; }
client_max_body_size 2m;
proxy_pass http://127.0.0.1:8080;
proxy_http_version 1.1;
proxy_request_buffering on;
proxy_pass_request_body on;
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_set_header Connection "";
access_log /var/log/nginx/webhook.access.log combined;
error_log /var/log/nginx/webhook.error.log warn;
}
}
Não defina ssl_ciphers à mão se você não for manter a lista. No Nginx 1.28 o padrão já acompanha TLS 1.2 e 1.3 quando ssl_protocols está restrito assim. Não ative HSTS neste bloco ainda. Strict-Transport-Security em certificado errado trava clientes por um ano. Webhook de servidor quase não usa HSTS; o que o provedor valida é o certificado apresentado no handshake, não o cabeçalho.
Atenção: rode o teste de sintaxe antes do reload. Se nginx -t falhar, não recarregue: um reload com configuração inválida é ignorado e o Nginx mantém os workers antigos com a configuração anterior. O que causa indisponibilidade é um restart ou reboot com configuração inválida. Por isso rode sempre nginx -t antes de qualquer operação.
sudo nginx -t
sudo systemctl reload nginx
A saída relevante do teste, quando o arquivo está válido, é:
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful
Location do webhook e corpo intacto
O corpo bruto é a entrada do HMAC. Qualquer transformação no caminho muda o digest e a assinatura boa passa a falhar, ou pior, alguém normaliza JSON dos dois lados e acha que "validou". Neste location evite qualquer módulo ou lógica que leia e reconstrua o corpo da requisição antes da validação, como proxy_set_body, handlers njs (js_content) que reemitam o payload, ou proxies e WAF intermediários que descompactem ou reescrevam o body. O formato combined do access_log não grava o corpo; não troque por um log_format com $request_body. Isso vazaria payload e, se alguém logar o cabeçalho de assinatura junto com o segredo em outro arquivo, facilita forjar o próximo evento.
proxy_request_buffering on é o padrão e é o que este validador espera. O Nginx lê o POST, guarda os bytes e encaminha ao upstream com Content-Length. Desligar o buffer para "não mexer no corpo" faz o upstream receber chunked em vários casos. O script abaixo lê pelo Content-Length. Buffer ligado não altera os bytes; só muda o momento em que eles são lidos.
location = /webhook não casa com /webhook/ nem com /webhook/extra. Cadastre a URL sem barra final. limit_except POST responde 403 para GET e PUT. Se o provedor faz um GET de verificação de URL, esse GET tem de ir para outro location, não para o que aceita evento. client_max_body_size 2m responde 413 antes da aplicação: nesse caso o HMAC nem roda. Suba o limite só até o máximo que o provedor documenta.
proxy_pass http://127.0.0.1:8080 sem URI no final repassa o caminho /webhook. Se você escrever proxy_pass http://127.0.0.1:8080/;, o upstream recebe / e o script responde 404. A porta 8080 não entra em firewall e não ganha listen público. Com o UFW ativo, não crie regra para 8080. Se for habilitar o UFW agora, inclua antes a porta do SSH que você já usa; este artigo não abre a 22 para a internet.
O redirecionamento da porta 80 existe para gente que cadastrar http:// por engano. O provedor deve ser configurado com https://hooks.seudominio.com.br/webhook. Vários provedores não seguem 301 em webhook e desistem. O 301 é rede de segurança, não o fluxo principal.
Conferência do HMAC em tempo constante
O segredo compartilhado é uma sequência de bytes, não uma frase "parecida". Um newline a mais no arquivo, um segredo colado com espaço ou um hex gerado de um lado e base64 do outro produz 401 eterno. Gere o valor no servidor, restrinja a leitura e copie para o painel do provedor por um canal que não seja o repositório.
Atenção: o comando seguinte grava por cima de /etc/webhook/secret. Se já existir um segredo em produção, pare. Trocar o arquivo sem atualizar o provedor derruba todos os eventos.
sudo useradd --system --create-home --home-dir /var/lib/webhook --shell /usr/sbin/nologin webhook
sudo install -d -o root -g webhook -m 750 /etc/webhook
sudo install -d -o root -g root -m 755 /opt/webhook
openssl rand -hex 32 | sudo tee /etc/webhook/secret >/dev/null
sudo chown root:webhook /etc/webhook/secret
sudo chmod 640 /etc/webhook/secret
O arquivo termina com newline. O serviço faz strip() e usa só o hex. O teste mais adiante lê do mesmo jeito. Leia o segredo diretamente como bytes no Python, conforme o serviço abaixo faz; não reconstrua a chave pelo shell com substituições de comando que possam tratar caracteres especiais de forma inconsistente.
Grave o validador em /opt/webhook/app.py. Ele não imprime a assinatura esperada e não escreve o corpo em log. Resposta 401 ou 204. A regra de negócio entra só depois do compare_digest retornar verdadeiro.
Atenção: ThreadingHTTPServer cria uma thread por conexão e não impõe limite de concorrência. Este processo escuta apenas em 127.0.0.1 e o Nginx é a única entrada pública, mas aplique limites de taxa e conexões no Nginx dimensionados para o provedor real. Para ambientes de alto volume, substitua por um servidor de aplicação com número de workers configurável e timeouts explícitos.
sudo tee /opt/webhook/app.py >/dev/null
Leia também
Otimizar Node-RED Dashboard 2.0 no FreeBSD 14.3 com Nginx e SSLChecklist: como hospedar múltiplos sites com Docker e NginxDNS Registro.br com Proxy Reverso Nginx sem queda