Assinatura HMAC em webhooks: como saber que a mensagem é legítima

A URL que recebe webhooks é pública: precisa ser, para que o parceiro consiga enviar eventos. Isso significa que qualquer pessoa que a descubra pode enviar requisições falsas — como confirmar um pagamento que nunca aconteceu.

Como a assinatura funciona

O parceiro e o seu sistema compartilham um segredo. A cada evento, o parceiro calcula um código (HMAC) a partir do conteúdo da mensagem e do segredo, e o envia num cabeçalho. Seu sistema recalcula o código com o mesmo segredo e compara.

import crypto from 'node:crypto'

function assinaturaValida(corpoBruto: Buffer, assinatura: string, segredo: string) {
  const esperado = crypto.createHmac('sha256', segredo).update(corpoBruto).digest('hex')
  return crypto.timingSafeEqual(Buffer.from(esperado), Buffer.from(assinatura))
}

Detalhes que fazem diferença

1. 1.Use o corpo bruto da requisição, antes de qualquer conversão para JSON — reformatar muda a assinatura.
2. 2.Comparação em tempo constante (timingSafeEqual), para não vazar informação.
3. 3.Verifique o horário do evento, quando enviado, para rejeitar mensagens antigas reenviadas.
4. 4.Segredo guardado com cuidado (Variáveis de ambiente e segredos: o .env não é cofre).
5. 5.Rejeite antes de processar.

E se o parceiro não assina?

Confirme os dados consultando a API do parceiro antes de agir, ou restrinja os IPs de origem quando ele os informa.

A recepção confiável — idempotência, filas e reconciliação — está em Webhooks confiáveis: idempotência, retentativas e ordem dos eventos, e a proteção de pagamentos em Idempotência: como evitar cobrança duplicada e pedidos repetidos.

Veja Segurança Anti-Hacker da We Codex ou fale com a gente.