Visão geral dos webhooks

Como o Wabox entrega eventos, o que vem em cada requisição e as garantias de entrega.

Webhooks são a única forma de receber alguma coisa do WhatsApp: mensagens, recibos, mudanças de conexão. O Wabox faz um POST HTTPS com JSON para a URL que você configurar, uma URL por tipo de evento.

Tipo	O que avisa	Página
received	Chegou uma mensagem (qualquer tipo) ou um evento de chat	received
delivery	Resultado de um envio feito pela API	delivery
message_status	Recibo de mensagem sua: enviada, entregue, lida, reproduzida	message_status
connected / disconnected	Estado da conexão mudou	conexão
chat_presence	Contato digitando, gravando, online	chat_presence

Configuração

No painel há dois lugares: Webhooks (menu lateral) define URLs e filtros para todas as instâncias do workspace, e a aba Webhooks e configurações gerais de cada instância permite sobrescrever só ali (desligue “Usar webhooks do workspace”). Instâncias novas herdam do workspace por padrão. Pela API, a configuração é sempre por instância:

curl -X PUT https://api.wabox.me/instances/{instance_id}/token/{token}/webhooks \
  -H "Content-Type: application/json" \
  -d '{
    "received_url": "https://seu-servidor.com/wabox",
    "delivery_url": "https://seu-servidor.com/wabox",
    "message_status_url": "https://seu-servidor.com/wabox",
    "connected_url": "https://seu-servidor.com/wabox",
    "disconnected_url": "https://seu-servidor.com/wabox",
    "chat_presence_url": null
  }'

Pode ser a mesma URL para tudo ou uma por tipo. null desliga o tipo. PUT /webhooks/{type} com { "value": "https://..." } altera um só. Os filtros decidem quais mensagens chegam.

Para não repetir a URL seis vezes, use o modo de URL única — todos os eventos vão para single_url e as *_url por tipo são ignoradas (roteie pelo type do corpo ou pelo header X-Wabox-Event; os ignore_*_callback continuam valendo):

curl -X PUT https://api.wabox.me/instances/{instance_id}/token/{token}/webhooks \
  -H "Content-Type: application/json" \
  -d '{ "single_url_enabled": true, "single_url": "https://seu-servidor.com/wabox" }'

use_workspace_webhooks (em GET /webhooks) diz se a instância está herdando a configuração do workspace. Definir qualquer URL não nula pela API desliga a herança automaticamente; envie { "use_workspace_webhooks": true } para voltar a herdar. Quem herda também é assinado com o secret do workspace (painel › Webhooks ou GET /partner/webhooks), um só para todas as instâncias; com configuração própria, vale o secret da instância.

Anatomia de uma entrega

POST /wabox HTTP/1.1
Host: seu-servidor.com
Content-Type: application/json
User-Agent: Wabox-Webhook/1.0
X-Wabox-Event: received
X-Wabox-Event-Id: 01J5Q8ZK3M4N5P6Q7R8S9T0V1X
X-Wabox-Instance-Id: 8f2a3c1e-6b7d-4e5f-9a0b-1c2d3e4f5a6b
X-Wabox-Signature: t=1786968300,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

{ "type": "received", "event_id": "01J5Q8ZK3M4N5P6Q7R8S9T0V1X", "instance_id": "8f2a3c1e-...", "momment": 1786968300000, ... }

Todo payload tem quatro campos em comum:

Campo	Tipo	Descrição
type	string	Tipo do evento (o mesmo do header X-Wabox-Event)
event_id	string	ULID único do evento. Chave de idempotência
instance_id	string	Instância que gerou o evento
momment	number	Epoch em milissegundos. O nome (com dois “m”) é herdado da z-api para facilitar migração

Garantias de entrega

• Ordem: entregas de uma mesma instância saem uma de cada vez, na ordem em que os eventos aconteceram. Instâncias diferentes são paralelas.
• Tentativas: você tem 10 s para responder 2xx. Caso contrário o Wabox tenta de novo após 10 s, 1 min, 10 min, 1 h e 6 h. Depois disso o evento é descartado e fica registrado como falha nos Logs de webhook do painel.
• Pelo menos uma vez: uma entrega pode repetir (por exemplo, você respondeu 200 mas a conexão caiu antes de o Wabox ler). Guarde event_id e ignore repetidos.
• Sem conteúdo em repouso: o Wabox não guarda as mensagens que trafegam; se todas as tentativas falharem, a mensagem não é recuperável pela API (o histórico recente cobre só o que o celular enviou ao parear). Mantenha o endpoint disponível.

Responda antes de processar. Se o seu handler demora (chama outra API, grava em banco lento), coloque o evento em uma fila interna e devolva 200 na hora. Um endpoint lento vira reenvios, que viram duplicidade.

Segurança

Verifique X-Wabox-Signature em toda entrega — é o que garante que veio do Wabox e não de alguém que descobriu a sua URL. Passo a passo com código em Assinatura dos webhooks. O segredo é o da instância ou, se ela herda os webhooks do workspace, o do workspace.

Testando

• Sem servidor público: use um túnel (ngrok, Cloudflare Tunnel) apontando para a sua máquina.
• Para ver o payload cru: qualquer serviço de “request bin”.
• No painel, Logs de webhook mostra cada tentativa com status HTTP, tempo de resposta e o corpo enviado, e permite reenviar manualmente.
• A aba Testes da instância dispara mensagens reais para um número seu e acompanha delivery e message_status — veja Diagnóstico.