O aviso automático (webhook) é uma chamada que a ProxyBox faz ao seu sistema quando algo acontece na instância: chegou uma mensagem, uma mensagem foi entregue ou lida, o número conectou ou desconectou. Assim o seu sistema não precisa perguntar o tempo todo. Este guia mostra como cadastrar o endereço, o JSON completo de cada evento, o formato opcional da Evolution e a conferência da assinatura em Node, Python, PHP e Go.
Cadastre o endereço
No painel, abra a instância, vá em Aviso automático para o seu sistema, digite o endereço (https://seu-sistema.com.br/whatsapp) e marque os avisos que quer receber. O painel confere o endereço antes de salvar e recusa o que não for seguro: http, endereço interno, porta fora do padrão, usuário e senha na URL.
Depois de salvar, use Testar aviso. O painel envia um aviso webhook.test assinado, mostra o código de resposta do seu sistema e guarda o resultado no histórico.
O que chega em cada aviso?
Resposta curta: um POST com corpo JSON, três cabeçalhos da ProxyBox e um envelope que sempre tem event, uid, instance, sent_at, occurred_at e data. O que muda de um evento para outro é só o data.
| Cabeçalho | Conteúdo |
|---|---|
X-ProxyBox-Event |
O nome do evento, por exemplo message.received |
X-ProxyBox-Delivery |
O uid do aviso (use para não processar duas vezes) |
X-ProxyBox-Signature |
t=<unix>,v1=<hex>: hora e assinatura |
Envelope, com o evento mais comum:
{
"event": "message.received",
"uid": "in_3EB0B430B6F8F1D0E053AC120E0A9E5C",
"instance": { "name": "Atendimento da loja", "slug": "atendimento-da-loja" },
"sent_at": "2026-11-11T14:05:01-03:00",
"occurred_at": "2026-11-11T17:05:00Z",
"data": {
"id": "3EB0B430B6F8F1D0E053AC120E0A9E5C",
"from": "5547999999999",
"name": "Maria",
"type": "text",
"text": "Oi, quero saber do pedido",
"reply_to": null,
"timestamp": "2026-11-11T17:05:00Z"
}
}
sent_at é quando a ProxyBox entregou; occurred_at é quando o fato aconteceu (pode vir nulo). O uid é estável: o mesmo fato reenviado leva o mesmo uid. Os exemplos abaixo mostram o envelope completo de cada evento, com valores de exemplo. [Recurso em beta: pode mudar.] Os eventos de mensagem, estado e restrição já existiam na versão 1; os de grupo, reação, edição, exclusão, chamada e agendamento chegaram na 1.1; os de lote, voto, aprovação e as respostas de botão chegaram na 1.2 e estão em beta.
Quais eventos existem?
| Evento | Quando |
|---|---|
message.received |
Chegou uma mensagem de um contato |
message.sent |
Saiu uma mensagem da instância (inclusive as enviadas pelo celular) |
message.status |
Entregue, lida ou ouvida |
connection.updated |
Conectou ou desconectou |
qr.updated |
QR novo para ler |
number.logged_out |
O WhatsApp desconectou o aparelho |
number.restricted |
O WhatsApp restringiu o número por um tempo |
group.message.received e group.message.sent |
Mensagem recebida ou enviada num grupo |
group.updated |
Alguém entrou, saiu, foi promovido ou o grupo mudou de nome |
message.reaction, message.edited, message.revoked |
Reação, edição e exclusão para todos |
call.received |
Chegou uma chamada |
message.scheduled_failed |
Um envio agendado falhou de vez |
message.batch |
Várias mensagens seguidas do mesmo chat, reunidas em um aviso (agrupar) |
poll.vote |
Alguém votou numa enquete (provado em aparelho real em 14/11/2026) |
presence.update |
Um contato que você assinou com POST /presence/subscribe ficou online ou offline (from, state, last_seen); beta |
approval.requested e approval.decided |
Uma mensagem espera aprovação humana ou foi decidida |
No painel você marca quais quer receber. Quem não está marcado não é entregue. Na prova em aparelho real de 10/11/2026, o motor entregou os avisos de mensagem (grupo termina em @g.us), reação, recibo de entrega e leitura (message.ack, que vira message.status) e chamada (call.offer, que vira call.received); a tradução para os nossos eventos segue o que o receptor faz.
Quer rodar isto agora? O sandbox é grátis, não precisa de número e já vem com a chave da API.
Testar grátisComo é o JSON de cada mensagem?
Resposta curta: message.received e message.sent têm os mesmos campos, trocando from por to. O type diz o que veio e, quando há arquivo, media traz só mime, filename e size. O arquivo se baixa pela rota de mídia recebida.
type pode ser text, image, video, audio, voice, document, sticker, location, contact ou poll. Em text, o campo text é a mensagem; nos tipos com arquivo, é a legenda (pode ser vazio).
message.received com imagem e resposta a uma mensagem
{
"event": "message.received",
"uid": "in_3EB0A1",
"instance": { "name": "Atendimento da loja", "slug": "atendimento-da-loja" },
"sent_at": "2026-11-11T14:06:10-03:00",
"occurred_at": "2026-11-11T17:06:09Z",
"data": {
"id": "3EB0A1",
"from": "5547999999999",
"name": "Maria",
"type": "image",
"text": "Segue o comprovante",
"media": { "mime": "image/jpeg", "filename": null, "size": 183204 },
"reply_to": "3EB0B430B6F8F1D0E053AC120E0A9E5C",
"timestamp": "2026-11-11T17:06:09Z"
}
}
message.received com mensagem de voz (type voice, media.mime audio/ogg; codecs=opus) e com documento (type document, media.filename "contrato.pdf") têm a mesma forma.
message.received com localização
{
"event": "message.received",
"uid": "in_3EB0A2",
"instance": { "name": "Atendimento da loja", "slug": "atendimento-da-loja" },
"sent_at": "2026-11-11T14:07:00-03:00",
"occurred_at": "2026-11-11T17:06:59Z",
"data": {
"id": "3EB0A2",
"from": "5547999999999",
"name": "Maria",
"type": "location",
"text": "",
"location": { "latitude": -26.9194, "longitude": -49.0661, "name": null, "address": null },
"reply_to": null,
"timestamp": "2026-11-11T17:06:59Z"
}
}
message.received com contato traz type igual a contact e contacts, uma lista de { "name": "Carlos", "phone": "5511988887777" }. Em enquete (poll), só o título chega em text; as opções e os votos não vêm no aviso.
{
"event": "message.sent",
"uid": "out_3EB0C3",
"instance": { "name": "Atendimento da loja", "slug": "atendimento-da-loja" },
"sent_at": "2026-11-11T14:08:02-03:00",
"occurred_at": "2026-11-11T17:08:01Z",
"data": {
"id": "3EB0C3",
"to": "5547999999999",
"type": "text",
"text": "Pedido confirmado.",
"timestamp": "2026-11-11T17:08:01Z"
}
}
message.status muda status para delivered, read ou played (áudio ouvido). Vem um aviso por mensagem e por estado, só para conversas individuais:
{
"event": "message.status",
"uid": "st_3EB0C3_read",
"instance": { "name": "Atendimento da loja", "slug": "atendimento-da-loja" },
"sent_at": "2026-11-11T14:09:40-03:00",
"occurred_at": "2026-11-11T17:09:39Z",
"data": { "id": "3EB0C3", "to": "5547999999999", "status": "read", "timestamp": "2026-11-11T17:09:39Z" }
}
Como é o JSON de uma mensagem de grupo?
Resposta curta: igual ao da conversa individual, com group (id e name) a mais. Em group.message.received, from e name são do participante que escreveu; em group.message.sent, não há to.
{
"event": "group.message.received",
"uid": "gin_3EB0D4",
"instance": { "name": "Atendimento da loja", "slug": "atendimento-da-loja" },
"sent_at": "2026-11-11T14:10:00-03:00",
"occurred_at": "2026-11-11T17:09:59Z",
"data": {
"id": "3EB0D4",
"group": { "id": "[email protected]", "name": "Pedidos da semana" },
"from": "5547999999999",
"name": "Maria",
"type": "text",
"text": "Alguém viu o pedido 4512?",
"reply_to": null,
"timestamp": "2026-11-11T17:09:59Z"
}
}
group.updated tem action com um destes valores: join (entrou), leave (saiu), promote, demote, joined (a própria instância entrou) ou name (o grupo mudou de nome). Os eventos de entrada, saída e promoção trazem participants (lista de telefones); name traz actor (quem mudou, pode ser nulo).
{
"event": "group.updated",
"uid": "gp_6c1f0b2a9d3e4f5a6b7c",
"instance": { "name": "Atendimento da loja", "slug": "atendimento-da-loja" },
"sent_at": "2026-11-11T14:11:00-03:00",
"occurred_at": "2026-11-11T17:10:58Z",
"data": {
"group": { "id": "[email protected]", "name": "Pedidos da semana" },
"action": "join",
"participants": ["5511988887777"],
"timestamp": "2026-11-11T17:10:58Z"
}
}
Como são reação, edição, exclusão e chamada?
Os três primeiros têm um objeto comum: message_id (a mensagem afetada), chat (telefone da conversa ou id do grupo), from (quem agiu), from_me e timestamp. Em grupo, vem também group.
{
"event": "message.reaction",
"uid": "rx_3EB0E5",
"instance": { "name": "Atendimento da loja", "slug": "atendimento-da-loja" },
"sent_at": "2026-11-11T14:12:00-03:00",
"occurred_at": "2026-11-11T17:11:59Z",
"data": {
"message_id": "3EB0C3",
"emoji": "👍",
"removed": false,
"chat": "5547999999999",
"from": "5547999999999",
"from_me": false,
"timestamp": "2026-11-11T17:11:59Z"
}
}
message.reaction:emojivazio eremovedverdadeiro quando a pessoa tira a reação.message.edited: acrescentatextcom o texto novo.message.revoked: acrescentarevoked_by_me(verdadeiro se foi a própria instância que apagou).
{
"event": "call.received",
"uid": "call_A1B2C3D4",
"instance": { "name": "Atendimento da loja", "slug": "atendimento-da-loja" },
"sent_at": "2026-11-11T14:13:00-03:00",
"occurred_at": "2026-11-11T17:12:59Z",
"data": {
"call_id": "A1B2C3D4",
"from": "5547999999999",
"from_jid": "[email protected]",
"name": "Maria",
"auto_rejected": false,
"platform": "android",
"timestamp": "2026-11-11T17:12:59Z"
}
}
call.received traz group se for chamada de grupo. Use o call_id em POST /calls/reject, ou ligue a recusa automática. from pode vir nulo quando o WhatsApp esconde o telefone (veja número e identidade).
Como são os avisos de estado da instância?
Resposta curta: quatro eventos: connection.updated (conectou ou desconectou), qr.updated (QR novo), number.logged_out (o WhatsApp tirou o aparelho) e number.restricted (restrição temporária).
{
"event": "connection.updated",
"uid": "cu_20261111140000_a1b2c3",
"instance": { "name": "Atendimento da loja", "slug": "atendimento-da-loja" },
"sent_at": "2026-11-11T14:14:00-03:00",
"occurred_at": null,
"data": { "status": "disconnected", "reason": "logged out" }
}
status é connected ou disconnected; reason é um texto curto (nulo quando conectou).
{
"event": "number.restricted",
"uid": "rb_9f3a0c1d2e4b5a69",
"instance": { "name": "Atendimento da loja", "slug": "atendimento-da-loja" },
"sent_at": "2026-11-11T14:15:00-03:00",
"occurred_at": "2026-11-11T17:14:58Z",
"data": { "reason": "reachout_timelock", "code": null, "expires_at": "2026-11-12T02:14:58Z" }
}
number.restricted liga a trava de contato novo. O guia restrição 463 explica o que fazer. number.logged_out traz reason e code (o código que o WhatsApp informou, quando existe). qr.updated traz expires_in, em segundos; o QR em si nunca viaja no aviso, só no painel e na rota GET /instance/qr.
{
"event": "message.scheduled_failed",
"uid": "sf_17_141600",
"instance": { "name": "Atendimento da loja", "slug": "atendimento-da-loja" },
"sent_at": "2026-11-12T09:16:00-03:00",
"occurred_at": null,
"data": { "schedule_id": 17, "op": "send.text", "to": "5547999999999", "error": "number_not_on_whatsapp", "message": "Esse número não tem WhatsApp." }
}
Quais valores status e reason posso receber?
| Campo | Valores |
|---|---|
message.status.status |
delivered, read, played |
connection.updated.status |
connected, disconnected |
connection.updated.reason |
texto curto, como logged out; nulo se conectou |
group.updated.action |
join, leave, promote, demote, joined, name |
number.restricted.reason |
reachout_timelock ou o texto informado pelo WhatsApp |
message.type |
text, image, video, audio, voice, document, sticker, location, contact, poll, button_reply (list_reply existe no formato, mas lista não funciona hoje) |
approval.decided.status |
sent, rejected, expired, failed |
Qual formato de aviso eu escolho: proxybox, evolution ou zapi?
Resposta curta: o padrão é proxybox, o envelope deste guia. Quem migra pode escolher, por instância, evolution ou zapi, e os mesmos fatos chegam nos nomes e na estrutura daquela API. A assinatura é sempre X-ProxyBox-Signature, calculada sobre o corpo que realmente sai. O formato zapi (ReceivedCallback, DeliveryCallback, MessageStatusCallback, ConnectedCallback e DisconnectedCallback) está descrito em migrar da Z-API; os nomes dos avisos de grupo e de chamada nesse formato ainda não foram conferidos contra a Z-API.
Como recebo no formato da Evolution?
Resposta curta: no painel, em Aviso automático, escolha format igual a evolution. Os mesmos fatos chegam com os nomes e a estrutura da Evolution v2, no envelope {event, instance, data, destination, date_time, sender, server_url, apikey}. O apikey vem sempre nulo; a validação é pelo cabeçalho X-ProxyBox-Signature, calculado sobre o corpo que realmente sai.
| Aviso da ProxyBox | event no formato evolution |
|---|---|
message.received, group.message.received, message.reaction |
messages.upsert |
message.sent, group.message.sent |
send.message |
message.status |
messages.update |
message.edited |
messages.edited |
message.revoked |
messages.delete |
connection.updated |
connection.update |
qr.updated |
qrcode.updated (sem o QR) |
group.updated |
group-participants.update, groups.upsert ou groups.update |
call.received |
call |
number.logged_out |
logout.instance |
number.restricted, message.scheduled_failed |
o nome da ProxyBox, no mesmo envelope |
A mesma mensagem recebida, no formato evolution:
{
"event": "messages.upsert",
"instance": "atendimento-da-loja",
"data": {
"key": { "remoteJid": "[email protected]", "fromMe": false, "id": "3EB0A1" },
"pushName": "Maria",
"status": "DELIVERY_ACK",
"message": { "imageMessage": { "mimetype": "image/jpeg", "fileLength": 183204, "caption": "Segue o comprovante" } },
"contextInfo": { "stanzaId": "3EB0B430B6F8F1D0E053AC120E0A9E5C" },
"messageType": "imageMessage",
"messageTimestamp": 1794416769
},
"destination": "https://seu-sistema.com.br/whatsapp",
"date_time": "2026-11-11T14:06:10-03:00",
"sender": "[email protected]",
"server_url": "https://proxybox.com.br/api/whatsapp/evolution",
"apikey": null
}
Um aviso de conexão vira {"event":"connection.update","data":{"instance":"atendimento-da-loja","state":"open","wuid":"[email protected]","statusReason":200}}, e uma entrada em grupo vira {"event":"group-participants.update","data":{"id":"[email protected]","participants":["[email protected]"],"action":"add"}}, ambos dentro do mesmo envelope. O arquivo da mídia nunca vai junto: baixe pela rota de mídia recebida, ou use o S3 para receber o endereço. A caixa do nome do evento é minúscula com ponto (messages.upsert), como a Evolution envia no código; códigos que comparam com MESSAGES_UPSERT precisam ajustar. Mapa completo: migrar da Evolution.
O que mudou na versão 1.2?
Resposta curta: quatro acréscimos nos avisos: o type de resposta de botão e de lista, o endereço da mídia guardada no seu S3, o lote message.batch e os eventos de aprovação. O type de resposta de botão foi provado em aparelho real em 14/11/2026; o S3, o lote message.batch e os eventos de aprovação seguem em beta.
Resposta a botão. Quando alguém toca num botão de resposta enviado por POST /messages/interactive, deve chegar um message.received com type igual a button_reply e data.selected com o id e o text escolhidos (lista e carrossel não funcionam hoje, então não existe list_reply na prática):
{
"event": "message.received",
"uid": "in_3EB0F1",
"instance": { "name": "Atendimento da loja", "slug": "atendimento-da-loja" },
"sent_at": "2026-11-12T10:00:02-03:00",
"occurred_at": "2026-11-12T13:00:01Z",
"data": { "id": "3EB0F1", "from": "5547999999999", "name": "Maria", "type": "button_reply", "text": "Confirmo", "selected": { "id": "sim", "text": "Confirmo" }, "reply_to": "3EB0B430B6F8F1D0E053AC120E0A9E5C" }
}
O envio dos botões foi provado em aparelho real em 12/11/2026, mas o aviso do toque recebido ainda não foi provado: trate selected como opcional.
Mídia no seu armazenamento. Com o S3 ligado, data.media ganha url (link temporário de 24 horas ou público) e stored. Se o envio ao bucket falhar, url não vem e stored é false, e o aviso chega do mesmo jeito.
"media": { "mime": "image/jpeg", "filename": null, "size": 183204, "url": "https://meu-bucket.s3.amazonaws.com/whatsapp/atendimento-da-loja/2026/11/3EB0A1.jpg?X-Amz-...", "stored": true }
Lote de mensagens. Com buffer_seconds ligado, o aviso message.batch reúne as mensagens seguidas do mesmo chat:
{
"event": "message.batch",
"uid": "bt_9c1e7a20d4",
"instance": { "name": "Atendimento da loja", "slug": "atendimento-da-loja" },
"sent_at": "2026-11-12T10:00:09-03:00",
"occurred_at": null,
"data": {
"chat": "5547999999999", "from": "5547999999999", "name": "Maria", "count": 2,
"text": "Oi\nqueria saber do pedido",
"messages": [ { "id": "3EB0A1", "type": "text", "text": "Oi", "timestamp": "2026-11-12T13:00:00Z", "media": null }, { "id": "3EB0A2", "type": "text", "text": "queria saber do pedido", "timestamp": "2026-11-12T13:00:04Z", "media": null } ]
}
}
Voto em enquete. poll.vote está na lista de eventos, com poll_id, voter, options e timestamp. Em 14/11/2026 um voto real foi entregue com o poll_id da enquete, o telefone de quem votou e a opção escolhida. O voto só chega quando a instância consegue ler a escolha por inteiro; se não conseguir, o aviso não é gerado. Por isso, não construa fluxo crítico só em cima dele.
Aprovação humana. approval.requested e approval.decided trazem approval_id, op, via e, na decisão, status (sent, rejected, expired ou failed) e decided_by. Nunca levam o texto da mensagem.
{
"event": "approval.decided",
"uid": "ad_41_sent",
"instance": { "name": "Atendimento da loja", "slug": "atendimento-da-loja" },
"sent_at": "2026-11-12T10:05:00-03:00",
"occurred_at": null,
"data": { "approval_id": 41, "op": "send.text", "status": "sent", "decided_by": "panel" }
}
De onde saem os avisos, e como libero no meu firewall?
Resposta curta: os avisos saem do endereço 209.222.97.88. Se o seu sistema só aceita conexões de IPs conhecidos, libere esse endereço (e, por precaução, confira a lista atual no painel, em Avisos, ou em /api-whatsapp/status?format=json, porque ela pode mudar). Bloquear o endereço faz os avisos falharem e entrarem no ciclo de novas tentativas.
E se eu não tenho endereço público?
Use o modo de consulta: o ajuste delivery_mode em pull guarda os avisos por 7 dias e você os busca com GET /events. Os envelopes são os mesmos deste guia, com um id numérico a mais. Veja receber por consulta. Com both, a ProxyBox entrega ao seu endereço e também guarda para consulta.
Confira a assinatura
A assinatura prova que o aviso veio da ProxyBox. O segredo aparece na página da instância, no bloco do aviso. Calcule o HMAC-SHA256 de "<t>.<corpo bruto>" com o segredo e compare com o v1. Recuse se o t tiver mais de 5 minutos de diferença da hora do seu servidor.
import crypto from "node:crypto";
function confere(headerAssinatura, corpoBruto, segredo) {
const partes = Object.fromEntries(headerAssinatura.split(",").map((p) => p.split("=")));
if (Math.abs(Date.now() / 1000 - Number(partes.t)) > 300) return false;
const esperado = crypto.createHmac("sha256", segredo).update(`${partes.t}.${corpoBruto}`).digest("hex");
const a = Buffer.from(esperado), b = Buffer.from(partes.v1 || "");
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
import hmac, hashlib, time
def confere(header, corpo_bruto: bytes, segredo: str) -> bool:
partes = dict(p.split("=", 1) for p in header.split(","))
if abs(time.time() - int(partes["t"])) > 300:
return False
esperado = hmac.new(segredo.encode(), partes["t"].encode() + b"." + corpo_bruto, hashlib.sha256).hexdigest()
return hmac.compare_digest(esperado, partes.get("v1", ""))
function confere(string $header, string $corpoBruto, string $segredo): bool
{
parse_str(str_replace(',', '&', $header), $p);
if (abs(time() - (int) ($p['t'] ?? 0)) > 300) {
return false;
}
$esperado = hash_hmac('sha256', ($p['t'] ?? '') . '.' . $corpoBruto, $segredo);
return hash_equals($esperado, $p['v1'] ?? '');
}
package wa
import (
"crypto/hmac"
"crypto/sha256"
"encoding/hex"
"math"
"strconv"
"strings"
"time"
)
func Confere(header string, corpoBruto []byte, segredo string) bool {
partes := map[string]string{}
for _, p := range strings.Split(header, ",") {
if kv := strings.SplitN(p, "=", 2); len(kv) == 2 {
partes[kv[0]] = kv[1]
}
}
t, err := strconv.ParseInt(partes["t"], 10, 64)
if err != nil || math.Abs(float64(time.Now().Unix()-t)) > 300 {
return false
}
mac := hmac.New(sha256.New, []byte(segredo))
mac.Write([]byte(partes["t"] + "."))
mac.Write(corpoBruto)
return hmac.Equal([]byte(hex.EncodeToString(mac.Sum(nil))), []byte(partes["v1"]))
}
Use sempre o corpo bruto da requisição, antes de decodificar o JSON: qualquer espaço a mais muda a assinatura.
Responda rápido e não repita
- Responda 2xx em até 10 segundos. Se o processamento for longo, guarde o aviso numa fila e responda na hora.
- Use o
uidpara deduplicar: se chegar de novo, ignore. - Não siga redirecionamento: os avisos não seguem. Cadastre o endereço final.
- Se o seu sistema ficar fora do ar, a ProxyBox tenta de novo: depois de 1 minuto, 5 minutos, 15 minutos, 1 hora e 6 horas. Passadas as cinco tentativas, o aviso aparece como desistido no histórico, com o motivo, e o painel tem o botão Reenviar.
- Se 10 avisos seguidos forem desistidos, o aviso automático é desligado para proteger a fila, e o painel avisa. Corrija o receptor e ligue de novo.
- A fila guarda até 5.000 avisos por instância. Como a mesma mensagem pode chegar mais de uma vez, a deduplicação pelo
uidnão é opcional.
Problemas comuns
| Sintoma | Causa provável |
|---|---|
| "Endereço aponta para uma rede interna" | O nome resolve para IP privado; use um endereço público |
| "Certificado https inválido" | Certificado vencido ou cadeia incompleta no seu servidor |
| "Sem resposta em 10 s" | O seu sistema demora; responda 2xx e processe depois |
| "Respondeu 4xx" | A rota do seu sistema recusou; confira a assinatura e o caminho |
| Assinatura nunca confere | Está calculando sobre o JSON já decodificado, ou o segredo está errado |
Veja também o guia de primeiros passos, o de n8n e o de segurança.
Veja também
- Receber WhatsApp sem webhook e agrupar mensagens
- Segurança da API de WhatsApp: chave e IPs
- Guardar mídia do WhatsApp no S3, R2 ou MinIO
- Migrar da Z-API: mapa de rotas
Índice completo: todos os guias. Sobre o produto: visão geral da API de WhatsApp da ProxyBox.
Autoria: equipe técnica da ProxyBox. Atualizado em 11/11/2026; campos conferidos no código do receptor de avisos, contra a versão 1.2 da API.