Skip to main content
Esta página cobre o ciclo completo sem depender de ferramenta: receber o webhook com o corpo cru, verificar X-Wabox-Signature, responder 200 rápido, enviar mensagens, tratar 429/402/409 e acompanhar o resultado no webhook delivery.
Base: https://api.wabox.me/instances/{instance_id}/token/{token}. O token vai na URL — trate-o como senha (Autenticação). O header Client-Token é obrigatório apenas se estiver ativado no workspace (Client-Token).

Receber webhooks

Toda entrega é um POST com Content-Type: application/json e os headers User-Agent: Wabox-Webhook/1.0, X-Wabox-Event (tipo), X-Wabox-Event-Id, X-Wabox-Instance-Id e X-Wabox-Signature. O Wabox espera 2xx em até 10 s; senão, reenvia em 10 s, 1 min, 10 min, 1 h e 6 h, com o mesmo event_id. Detalhes em Visão geral dos webhooks. Três regras para o endpoint:
  1. Leia o corpo cru antes de qualquer parser de JSON — a assinatura é calculada sobre os bytes originais.
  2. Verifique a assinatura e a janela de tempo antes de confiar no conteúdo.
  3. Responda 200 imediatamente e processe depois (fila, worker, setImmediate, tarefa em background). Não chame a API do Wabox nem serviços lentos dentro do handler.
A assinatura tem o formato t=<unix>,v1=<hex>, com v1 = HMAC-SHA256(secret, t + "." + corpo_cru). O secret (whsec_…) é por instância e aparece em GET /webhooks e no dashboard. Rejeite t fora de uma janela de ~5 minutos. Mais em Assinatura de webhooks.
Guarde os event_id processados (chave única no banco ou SET NX no Redis com expiração de alguns dias) e descarte repetidos. Reentregas trazem o mesmo event_id, e uma resposta ao cliente enviada duas vezes é o erro mais comum de webhook.

Enviar mensagens

POST .../send-text com phone (só dígitos, DDI + DDD + número) e message. Outros campos, como reply_to_message_id e mentioned, estão na API Reference.
A resposta chega na hora, com a mensagem já na fila:
message_id já é o id definitivo da mensagem no WhatsApp (id é um alias). Guarde-o: é a chave para cruzar com os webhooks delivery e message_status.

Tratar erros

Todo erro vem como { "error": { "code": "...", "message": "..." } }. Os que sua integração precisa tratar de forma diferente:
O limite é por instância (token bucket). A resposta traz Retry-After em segundos e os headers X-RateLimit-Limit e X-RateLimit-Remaining. Espere o tempo indicado e repita a requisição. Não faça retry imediato em loop: cada tentativa consome o mesmo balde.Um 429 também pode vir com code: "queue_full" quando a fila de saída da instância está no limite — nesse caso, reduza o ritmo de envio em vez de repetir.
A instância existe, mas o workspace não tem plano ativo (trial encerrado ou pagamento pendente). Repetir não resolve; alerte quem administra a conta. Trate como erro permanente até o plano ser regularizado.
A instância não está com o WhatsApp conectado (QR não lido, sessão caiu ou foi deslogada). Rotas imediatas — contatos, grupos, perfil — falham com esse código. O envio de mensagens, por padrão, entra na fila e sai quando o número reconectar; se a instância estiver configurada para recusar envios enquanto desconectada, a resposta é 409 com code: "queue_disabled_while_disconnected".Para reagir, consulte GET .../status ou assine os webhooks connected/disconnected (Conexão) e pause os envios enquanto o número estiver fora.
A lista completa de códigos está em Erros, e a estratégia de retry em Rate limit e erros. Um esqueleto de retry que respeita esses três casos:

Acompanhar a entrega

status: "queued" não é confirmação de envio. O resultado chega no webhook delivery, na delivery_url da instância, com o mesmo message_id e wabox_id da resposta:
Sem error, a mensagem saiu. Quando o envio falha, o mesmo evento traz error (texto) e error_code (por exemplo, número sem WhatsApp ou mídia inválida) — persista isso ao lado do message_id que você guardou na resposta. Os recibos (enviado, recebido, lido) vêm depois, no webhook message_status, com ids[] contendo o mesmo message_id. Enquanto a mensagem ainda não saiu, GET .../queue lista a fila da instância e DELETE .../queue/{wabox_id} remove um item — veja Fila e reenvio.