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 SaaS chama quando chega uma mensagem num número. Cada número tem a própria lista de destinos.
Configurar
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:
{"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.
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:
{
"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:
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);
}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:
signing | Assinatura |
|---|---|
own | Com o segredo próprio do endereço. |
deployment | Endereç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. |
none | Endereç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):
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
2xxrá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
httpsparahttp. - 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.idpara não processar a mesma mensagem duas vezes.