Pular para o conteúdo
apiwpp
Termo

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:

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çalhoConteúdo
X-Sales-TimestampO momento da tentativa, em segundos unix
X-Sales-Signaturesha256= 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:

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.

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.

Conecte seu primeiro número hoje.

7 dias grátis, sem cartão de crédito.