Ir para o conteúdo

Webhooks

Receber as mensagens no seu servidor, conferir a assinatura e entender as entregas.

Um webhook é um endereço do seu servidor que a API WAAPI Max chama quando chega uma mensagem num número. Cada número tem a própria lista de destinos.

Configurar

bash
curl -X POST "$API_URL/api/v1/instances/<id>/webhook" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"targets": [{"url": "https://exemplo.com.br/webhooks/waapi", "events": ["message"]}]}'

Essas rotas pedem a chave do número (a chave de API não abre o webhook). O POST troca a lista inteira de destinos do número.

A resposta traz cada destino com o campo signing, e cada endereço novo ganha um segredo de assinatura próprio (whsec_...), que vem em secret só nesta resposta:

json
{"status": "updated", "targets": [{"url": "https://exemplo.com.br/webhooks/waapi", "events": ["message"], "signing": "own", "secret": "whsec_..."}]}

Guarde o segredo agora: nenhuma leitura o mostra de novo. Um endereço que já estava salvo mantém o segredo dele.

GET na mesma rota devolve os destinos atuais deste número, com o endereço mascarado (trechos do caminho e da query aparecem como … e ••••) e sem o segredo. Para manter um destino ao salvar a lista de novo, mande o endereço completo ou o mascarado exatamente como a leitura trouxe: os dois mantêm o mesmo segredo. Se dois endereços salvos têm a mesma máscara, a resposta é 400 AMBIGUOUS_MASKED_TARGET: mande o endereço completo.

O webhook vale só para o número da rota: os eventos de outro número não vão para esses endereços, e a configuração fica guardada (sobrevive a reinício da API). Para receber eventos de vários números, configure cada um. A área do cliente também configura e testa o webhook, na aba Webhook de cada número.

Configurou um webhook antes da mudança para um webhook por número? Aquela configuração valia para todos os números e não ficava guardada: cadastre de novo o endereço em cada número.

A URL precisa ser https, sem usuário e senha na URL, numa porta padrão ou acima de 1024, e não pode apontar para endereço interno (localhost, rede privada, *.local, *.internal...). Uma URL recusada responde 400 com uma mensagem estável, como webhook url must be https, e nada é salvo.

O plano limita o total de destinos de webhook da conta, somando todos os números: um salvamento que aumenta a lista além do limite responde 403 com {"code": "plan_limit", "limit": "max_webhooks"}, e com a conta suspensa, 403 ACCOUNT_SUSPENDED. Manter ou diminuir a lista sempre passa.

O que chega

A API faz um POST com JSON e o cabeçalho X-WAAPI-Event com o nome do evento:

json
{
  "event": "message",
  "timestamp": "2026-01-15T14:03:22Z",
  "instance_id": "a1b2c3d4-0000-4000-8000-000000000000",
  "data": {
    "id": "3EB0C0FFEE1234567890",
    "from": "5511999990000@s.whatsapp.net",
    "sender": "5511999990000@s.whatsapp.net",
    "body": "Quero fazer um pedido",
    "timestamp": "2026-01-15T14:03:21Z",
    "is_group": false,
    "direction": "inbound"
  }
}

O evento message traz só mensagens de verdade: os avisos internos do WhatsApp (sincronização, chaves, configurações) não chegam ao webhook. Mídia vem em data.media, com a legenda em data.media_caption.

Conferir a assinatura

Cada entrega leva o cabeçalho X-WAAPI-Signature: o HMAC-SHA256 do corpo, em hexadecimal, calculado com o segredo daquele endereço. Cada destino tem o seu, então um sistema que recebe em vários endereços confere cada um com o segredo certo. Calcule o HMAC sobre o corpo exatamente como chegou, antes de qualquer parse, e compare em tempo constante:

js
import { createHmac, timingSafeEqual } from "node:crypto";

export function assinaturaValida(corpoBruto, assinatura, segredo) {
  const esperada = createHmac("sha256", segredo).update(corpoBruto).digest("hex");
  const a = Buffer.from(esperada, "hex");
  const b = Buffer.from(assinatura ?? "", "hex");
  return a.length === b.length && timingSafeEqual(a, b);
}
python
import hmac, hashlib

def assinatura_valida(corpo_bruto: bytes, assinatura: str, segredo: str) -> bool:
    esperada = hmac.new(segredo.encode(), corpo_bruto, hashlib.sha256).hexdigest()
    return hmac.compare_digest(esperada, assinatura or "")

Recuse a entrega (por exemplo com 401) quando a assinatura não bater.

O campo signing de cada destino diz como ele é assinado:

signingAssinatura
ownCom o segredo próprio do endereço.
deploymentEndereço salvo antes dos segredos por endereço: assinado com um segredo comum da sua API, que não é entregue ao cliente. Gere um segredo próprio para conferir a assinatura.
noneEndereço antigo sem segredo: as entregas chegam sem X-WAAPI-Signature. Gere um segredo próprio.

Para trocar o segredo (ou gerar um para um endereço antigo):

bash
curl -X POST "$API_URL/api/v1/instances/<id>/webhook/rotate-secret" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://exemplo.com.br/webhooks/waapi"}'

O url pode ser o endereço completo ou o mascarado da leitura. Sem corpo, todos os destinos do número ganham segredo novo. O segredo novo vem em secret só nesta resposta, e o anterior deixa de valer na hora: atualize o seu sistema logo em seguida. Um endereço que não está salvo responde 404 WEBHOOK_NOT_FOUND.

Na área do cliente, a aba Webhook do número mostra o tipo de assinatura de cada endereço e tem Trocar segredo.

O webhook de um cluster é outro: ele é configurado em PUT /api/v1/clusters/<id>/webhook com webhook_url e webhook_token, e cada entrega leva Authorization: Bearer <webhook_token>. Os eventos são cluster.message.sent, cluster.message.received e os de erro (cluster.error.*).

Entregas

  • Responda 2xx rápido. Cada entrega tem 10 s no total, e a sua resposta não precisa de corpo.
  • A API segue no máximo 2 redirecionamentos, e nunca para endereço interno ou de https para http.
  • O endereço é conferido de novo a cada entrega, inclusive depois do DNS: um domínio que passa a apontar para rede privada deixa de receber.
  • Cada entrega é tentada uma vez. Se o seu servidor estiver fora do ar ou responder erro, aquela entrega se perde: recupere o que faltou em GET /api/v1/instances/<id>/messages.
  • Use data.id para não processar a mesma mensagem duas vezes.