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 é umPOST 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:
- Leia o corpo cru antes de qualquer parser de JSON — a assinatura é calculada sobre os bytes originais.
- Verifique a assinatura e a janela de tempo antes de confiar no conteúdo.
- Responda
200imediatamente e processe depois (fila, worker,setImmediate, tarefa em background). Não chame a API do Wabox nem serviços lentos dentro do handler.
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.
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.
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:
429 rate_limited — limite de requisições por instância
429 rate_limited — limite de requisições por instância
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.402 subscription_required — workspace sem assinatura ativa
402 subscription_required — workspace sem assinatura ativa
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.
409 instance_not_connected — número desconectado
409 instance_not_connected — número desconectado
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.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:
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.