O que é HMAC e assinatura de webhook
HMAC é um código calculado a partir de uma mensagem e de um segredo compartilhado, com uma função de hash como SHA-256. Quem tem o segredo recalcula o código e confirma que a mensagem veio de quem diz e não foi alterada no caminho.
Atualizado em
HMAC (Hash-based Message Authentication Code) é um código de autenticação de mensagem. Ele é calculado com uma função de hash, como a SHA-256, sobre duas coisas: o conteúdo da mensagem e um segredo que só as duas pontas conhecem. O resultado é uma sequência de caracteres que funciona como uma assinatura.
Quem recebe a mensagem faz a mesma conta com o mesmo segredo. Se o resultado bate com a assinatura recebida, a mensagem veio de quem conhece o segredo e chegou sem alterações. Se não bate, ela deve ser recusada.
Por que assinar um webhook
Um webhook é um endereço público do seu sistema. Qualquer pessoa que descubra a URL pode enviar um POST para ela, com um evento inventado: uma mensagem que nunca chegou, um pagamento confirmado que não existiu. A assinatura HMAC resolve dois problemas de uma vez:
- Autenticidade: só quem tem o segredo consegue produzir uma assinatura válida, então o evento veio mesmo do serviço.
- Integridade: qualquer byte alterado no corpo muda o resultado, então o conteúdo não foi mexido no caminho.
Um hash simples, sem segredo, não serve para isso: qualquer pessoa pode calcular o SHA-256 de um corpo falso. O segredo é o que transforma o hash numa assinatura.
Como a apiwpp assina
Quando o projeto tem um segredo de webhook definido, cada tentativa de entrega traz dois cabeçalhos:
| Cabeçalho | Conteúdo |
|---|---|
X-Sales-Timestamp | O momento da tentativa, em segundos unix |
X-Sales-Signature | sha256= seguido do HMAC-SHA256 em hexadecimal de timestamp + "." + corpo bruto |
O timestamp entra na conta para barrar a repetição: alguém que capture uma entrega válida não consegue reenviá-la horas depois, porque o seu código recusa timestamps a mais de 300 segundos do relógio do servidor. Cada nova tentativa é assinada de novo, com o timestamp daquele momento.
Como verificar
Três cuidados fazem a diferença entre uma verificação correta e uma que só parece correta:
- Use o corpo bruto, os bytes exatamente como chegaram. Se você converter o JSON em objeto e serializar de novo, a ordem dos campos ou os espaços podem mudar, e a assinatura não confere.
- Recuse um segredo vazio. Um HMAC com chave vazia pode ser calculado por qualquer pessoa. Se o segredo não chegou ao processo, recuse tudo.
- Compare em tempo constante. Uma comparação comum de strings para no primeiro caractere diferente, e o tempo de resposta revela quantos caracteres estavam certos. Com muitas tentativas, um atacante poderia montar a assinatura aos poucos. Funções como
timingSafeEqual(Node.js),hash_equals(PHP) ehmac.compare_digest(Python) levam sempre o mesmo tempo.
Em Node.js, com o corpo bruto em um Buffer:
import { createHmac, timingSafeEqual } from 'node:crypto'
const SECRET = process.env.WHATSAPP_WEBHOOK_SECRET
if (!SECRET) throw new Error('WHATSAPP_WEBHOOK_SECRET não está definido')
export function isSigned(rawBody, timestamp, signature) {
if (!/^\d+$/.test(timestamp ?? '') || !signature) return false
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false
const mac = createHmac('sha256', SECRET).update(`${timestamp}.`).update(rawBody).digest('hex')
const expected = Buffer.from(`sha256=${mac}`)
const received = Buffer.from(signature)
return expected.length === received.length && timingSafeEqual(expected, received)
}
Em Python, a mesma lógica:
import hashlib
import hmac
import time
def is_signed(raw_body: bytes, timestamp: str, signature: str, secret: str) -> bool:
if not secret or not timestamp.isdigit() or not signature:
return False
if abs(time.time() - int(timestamp)) > 300:
return False
mac = hmac.new(secret.encode(), timestamp.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(f"sha256={mac}".encode(), signature.encode())
O tutorial webhooks do WhatsApp mostra o endpoint completo, com a versão em PHP, e a página de webhooks assinados descreve as entregas.
Perguntas frequentes
HMAC é criptografia?
Não. O HMAC não esconde o conteúdo: o corpo do webhook continua legível. Ele só prova quem enviou e que nada foi alterado. A confidencialidade no caminho vem do https, que é obrigatório no endereço do webhook.
Onde fica o segredo do webhook?
O segredo é definido no projeto e deve ficar só no servidor que recebe os eventos, numa variável de ambiente ou num cofre de segredos. Nunca o coloque no código do navegador, em logs ou no repositório.
O que acontece se eu recusar uma entrega com assinatura inválida?
Responda 401. A apiwpp trata qualquer resposta fora da faixa 2xx como falha e tenta de novo; se a assinatura continuar inválida, a entrega termina como falha no registro. Nesse caso, confira se o segredo configurado no seu servidor é o mesmo do projeto.
Outros termos
Todos: Glossário →Webhook é uma chamada HTTP que um serviço faz para um endereço do seu sistema quando um evento acontece, como uma mensagem recebida. Em vez de perguntar de tempos em tempos se há novidades, o seu sistema é avisado na hora.
Uma operação é idempotente quando repeti-la tem o mesmo efeito que fazê-la uma vez. Em APIs, isso se consegue com uma chave de idempotência: o cliente manda o mesmo identificador em cada tentativa e o servidor reconhece a repetição em vez de executar de novo.
API não oficial do WhatsApp é um serviço que conecta um número comum pelo protocolo do WhatsApp Web, como um aparelho conectado, e expõe envio e recebimento de mensagens por HTTP. Não passa pela Meta: não exige aprovação, mas o número pode ser restringido.