técnico · resposta com fontes
Verificação de assinatura de webhook
A verificação de assinatura de webhook é um processo de segurança em que o receptor valida uma assinatura criptográfica anexada a uma requisição HTTP recebida. Isso garante que o payload foi enviado pelo provedor confiável e não foi alterado durante o trânsito.
Definição
A verificação de assinatura de webhook é um mecanismo usado para autenticar a origem de um evento de webhook. Quando um provedor como o Resend ou o SendGrid envia uma notificação sobre um evento de e-mail, ele inclui um hash do payload assinado com uma chave secreta. O servidor receptor usa a mesma chave secreta para recalcular o hash e compará-lo com a assinatura enviada no cabeçalho da requisição.
Processo técnico
O provedor gera um hash HMAC usando um segredo compartilhado e o corpo da requisição. Esse hash é enviado em um cabeçalho, muitas vezes chamado X-Signature ou algo parecido. O receptor captura o corpo bruto da requisição e o cabeçalho de assinatura. Em seguida, calcula seu próprio hash HMAC usando o segredo compartilhado. Se o hash calculado corresponder ao valor do cabeçalho, a requisição é autêntica. Se forem diferentes, a requisição é rejeitada como não autorizada.
Importância para remetentes
Sem verificação, qualquer pessoa que conheça a URL do seu webhook pode enviar dados falsos ao seu servidor. Isso pode causar atualizações incorretas no banco de dados, como marcar um e-mail entregue como bounce. Implementar a verificação evita ataques de spoofing e garante que sua aplicação só reaja a eventos legítimos disparados pela sua infraestrutura de e-mail.
Notas operacionais
Um erro comum é fazer o parsing do corpo da requisição para um objeto JSON antes de verificar a assinatura. Como os parsers de JSON podem alterar espaços em branco ou a ordem das chaves, a string resultante pode não corresponder ao payload original usado pelo provedor. Use sempre o corpo bruto da requisição, sem parsing, nos cálculos de HMAC para evitar falhas de verificação.
Exemplo de implementação
Em um ambiente Node.js, o desenvolvedor usaria o módulo crypto para criar um hash hmac sha256 do corpo bruto com o segredo do provedor. Esse resultado é então comparado com o cabeçalho de assinatura usando uma função de comparação em tempo constante, para evitar ataques de timing. O SendHQ oferece ferramentas gratuitas em https://sendhq.cc/tools para ajudar a gerenciar diversas configurações de e-mail que normalmente precedem a configuração de webhooks.
Perguntas que as equipes fazem
O que acontece se a chave secreta vazar?
Se a chave secreta for comprometida, um invasor pode assinar requisições falsas que seu servidor aceitará como válidas. Você precisa fazer a rotação da chave secreta imediatamente no painel do provedor e atualizar as variáveis de ambiente do seu servidor.
O HTTPS dispensa a verificação de assinatura?
Não. O HTTPS criptografa os dados em trânsito e verifica a identidade do servidor, mas não verifica se o cliente específico que envia a requisição é o seu provedor de e-mail autorizado.
Por que usar HMAC em vez de uma simples chave de API?
As assinaturas HMAC comprovam que o conteúdo da mensagem não foi adulterado. Uma chave de API estática em um cabeçalho só prova que o remetente conhece a chave, não que o payload está intacto.
Fontes primárias
- Resend Documentation — Resend (em inglês)
- Postmark Developer Documentation — Postmark (em inglês)
- SendGrid Documentation — Twilio SendGrid (em inglês)