Visão geral dos webhooks

​

Configuração

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
  }'

​

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, ... }

​

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 o conteúdo das mensagens; se todas as tentativas falharem, a mensagem não é recuperável pela API. Mantenha o endpoint disponível.

​

Segurança

​

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.