API atual/Referência completa/Webhooks e eventos

Callback central do WhatsApp

URL única da Meta que encaminha cada mensagem à loja ou ao sistema dono do número, e a rota para cadastrar o destino de um número.

A Meta permite uma única URL de callback por aplicativo, mas a plataforma atende muitas lojas, cada uma com os seus números. O callback central resolve isso: a Meta chama sempre a mesma URL, a plataforma descobre o número comercial dentro da mensagem e encaminha para o destino cadastrado para aquele número. O destino pode ser a própria plataforma (uma loja Venddor) ou um sistema externo seu.

Verificar a URL central

Desafio de verificação da Meta para a URL central. Funciona como o da loja, mas o token de verificação é o da plataforma e não pertence a uma loja.

GET/api/v1/webhooks/whatsapp-routesPública

Verificação da Meta na URL central

Parâmetros de consulta

hub.modestringobrigatório

subscribe

Sempre subscribe.

hub.verify_tokenstringobrigatório

Token de verificação da plataforma.

hub.challengestringobrigatório

Texto que deve ser devolvido.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/webhooks/whatsapp-routes?hub.mode=subscribe&hub.verify_token=$VERIFY_TOKEN&hub.challenge=1158201444"

Resposta

200Desafio devolvido (texto puro)

text

1158201444

Erros

Status	Quando	Corpo
400	`hub.mode` diferente de `subscribe`	`{"error":"invalid hub.mode"}`
403	Token errado	`{"error":"invalid verify token"}`

Receber e encaminhar mensagens

A Meta envia aqui todas as notificações do aplicativo. A plataforma confere a assinatura, extrai o número comercial e procura a rota ativa daquele número:

Se a rota aponta para a plataforma, a mensagem é processada pela loja dona do número.
Se aponta para uma URL externa, a plataforma encaminha o mesmo corpo para ela (veja o contrato abaixo).
Se não há rota, a notificação é ignorada.

A resposta à Meta é sempre 200 quando a assinatura confere, mesmo que o encaminhamento falhe, para a Meta não repetir a notificação e sobrecarregar um destino fora do ar.

POST/api/v1/webhooks/whatsapp-routesPública

Entrada central de notificações da Meta

Cabeçalhos

X-Hub-Signature-256stringobrigatório

sha256= mais o HMAC-SHA256 do corpo bruto, com o segredo do app da Meta.

Corpo da requisição

(JSON)objectobrigatório

Notificação da Meta no formato do WhatsApp Cloud API.

Exemplo de requisição

bash

BODY='{"object":"whatsapp_business_account","entry":[{"id":"102290129340398","changes":[{"field":"messages","value":{"messaging_product":"whatsapp","metadata":{"display_phone_number":"551140041234","phone_number_id":"106540352242922"},"statuses":[{"id":"wamid.HBgM","status":"delivered","timestamp":"1791748900","recipient_id":"5511987654321"}]}}]}]}'
SIG="sha256=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$META_APP_SECRET" | sed 's/^.* //')"

curl -X POST "$BASE_URL/api/v1/webhooks/whatsapp-routes" \
  -H "Content-Type: application/json" \
  -H "X-Hub-Signature-256: $SIG" \
  -d "$BODY"

Resposta

200Processado pela plataforma

json

{"status":"ok"}

200Encaminhado a um destino externo

json

{"status":"routed"}

Outros 200: {"status":"forward_failed"} (o destino externo falhou), {"status":"ignored"} (nenhuma loja dona do número) e {"status":"process_error"}.

Erros

Status	Quando	Corpo
400	Não foi possível ler o corpo	`{"error":"failed to read body"}`
401	Assinatura inválida	`{"error":"invalid signature"}`
403	Segredo do app não cadastrado	`{"error":"app secret not configured"}`
503	Credenciais da plataforma indisponíveis, ou limite de 20 segundos excedido	`{"error":"platform credentials unavailable"}`

Contrato de quem recebe o encaminhamento

Quando a rota do número aponta para um sistema seu, a plataforma faz um POST na webhook_url cadastrada com o mesmo corpo recebido da Meta e estes cabeçalhos:

Cabeçalho	Valor
`Content-Type`	`application/json`
`X-Route-Name`	Nome da rota
`X-Business-Phone`	Número comercial, só dígitos, com DDI
`X-Route-Key` e `X-Route-Api-Key`	Chave própria da rota, para o seu servidor reconhecer a origem

Responda 2xx em até 12 segundos. Outro status ou demora é registrado como falha de encaminhamento e não é repetido pela plataforma.

Cadastrar uma rota

Sistemas externos cadastram (ou atualizam) o destino de um número chamando esta rota com a chave mestra de rotas, que a equipe Venddor fornece. É um upsert por telefone: registrar o mesmo número de novo atualiza a rota existente e mantém a chave dela.

POST/api/v1/webhooks/whatsapp-routes/registerPública

Cadastrar ou atualizar a rota de um número

Cabeçalhos

X-Api-Keystringobrigatório

Chave mestra de rotas. Também aceita no parâmetro de consulta api_key.

Corpo da requisição

namestringobrigatório

Nome da rota, para você reconhecê-la.

phone_numberstringobrigatório

Número comercial brasileiro. Aceita máscara; o DDI 55 é acrescentado se faltar. Entre 12 e 15 dígitos no total.

webhook_urlstring

URL que receberá as notificações do número. Se omitida, usa o destino padrão da plataforma.

verify_tokenstring

Token de verificação desta rota. Se omitido, a plataforma usa um padrão.

activebooleanpadrão: true

false desativa a rota sem apagá-la.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/webhooks/whatsapp-routes/register" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $ROUTES_MASTER_KEY" \
  -d '{"name":"Loja Centro","phone_number":"(11) 4004-1234","webhook_url":"https://api.minhaempresa.example.com/whatsapp/inbound","active":true}'

Resposta

200Rota registrada

json

{
  "success": true,
  "message": "Route registered successfully",
  "data": {
    "route_id": 17,
    "name": "Loja Centro",
    "phone_number": "551140041234",
    "webhook_url": "https://api.minhaempresa.example.com/whatsapp/inbound",
    "verify_token": "meu-token-de-verificacao",
    "api_key": "rk_live_example_not_real",
    "active": true,
    "created_at": "2026-10-11T20:30:00Z",
    "updated_at": "2026-10-11T20:30:00Z"
  }
}

Campos da resposta

successboolean

true quando registrou.

messagestring

Mensagem em inglês.

dataobject

A rota.

route_idinteger

Id numérico da rota.

namestring

Nome.

phone_numberstring

Número normalizado, só dígitos, com DDI.

webhook_urlstring

Destino das notificações.

verify_tokenstring

Token de verificação da rota.

api_keystring

Chave própria da rota, enviada em X-Route-Key ao encaminhar. Guarde-a para reconhecer a origem.

activeboolean

Se a rota está ativa.

created_atstring

Criação, RFC 3339.

updated_atstring

Última alteração, RFC 3339.

Erros

Status	Quando	Corpo
400	Corpo inválido	`{"success":false,"message":"Invalid request body","data":null}`
400	`name` ausente ou telefone fora do formato	`{"success":false,"message":"name is required","data":null}`
401	Sem chave de API	`{"success":false,"message":"API key required","data":null}`
403	Chave de API inválida	`{"success":false,"message":"Invalid API key","data":null}`

Veja também

API atual/Referência completa/Webhooks e eventos

Callback central do WhatsApp

URL única da Meta que encaminha cada mensagem à loja ou ao sistema dono do número, e a rota para cadastrar o destino de um número.

Verificar a URL central

Desafio de verificação da Meta para a URL central. Funciona como o da loja, mas o token de verificação é o da plataforma e não pertence a uma loja.

GET/api/v1/webhooks/whatsapp-routesPública

Verificação da Meta na URL central

Parâmetros de consulta

hub.modestringobrigatório

subscribe

Sempre subscribe.

hub.verify_tokenstringobrigatório

Token de verificação da plataforma.

hub.challengestringobrigatório

Texto que deve ser devolvido.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/webhooks/whatsapp-routes?hub.mode=subscribe&hub.verify_token=$VERIFY_TOKEN&hub.challenge=1158201444"

Resposta

200Desafio devolvido (texto puro)

text

1158201444

Erros

Status	Quando	Corpo
400	`hub.mode` diferente de `subscribe`	`{"error":"invalid hub.mode"}`
403	Token errado	`{"error":"invalid verify token"}`

Receber e encaminhar mensagens

A Meta envia aqui todas as notificações do aplicativo. A plataforma confere a assinatura, extrai o número comercial e procura a rota ativa daquele número:

Se a rota aponta para a plataforma, a mensagem é processada pela loja dona do número.
Se aponta para uma URL externa, a plataforma encaminha o mesmo corpo para ela (veja o contrato abaixo).
Se não há rota, a notificação é ignorada.

A resposta à Meta é sempre 200 quando a assinatura confere, mesmo que o encaminhamento falhe, para a Meta não repetir a notificação e sobrecarregar um destino fora do ar.

POST/api/v1/webhooks/whatsapp-routesPública

Entrada central de notificações da Meta

Cabeçalhos

X-Hub-Signature-256stringobrigatório

sha256= mais o HMAC-SHA256 do corpo bruto, com o segredo do app da Meta.

Corpo da requisição

(JSON)objectobrigatório

Notificação da Meta no formato do WhatsApp Cloud API.

Exemplo de requisição

bash

BODY='{"object":"whatsapp_business_account","entry":[{"id":"102290129340398","changes":[{"field":"messages","value":{"messaging_product":"whatsapp","metadata":{"display_phone_number":"551140041234","phone_number_id":"106540352242922"},"statuses":[{"id":"wamid.HBgM","status":"delivered","timestamp":"1791748900","recipient_id":"5511987654321"}]}}]}]}'
SIG="sha256=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$META_APP_SECRET" | sed 's/^.* //')"

curl -X POST "$BASE_URL/api/v1/webhooks/whatsapp-routes" \
  -H "Content-Type: application/json" \
  -H "X-Hub-Signature-256: $SIG" \
  -d "$BODY"

Resposta

200Processado pela plataforma

json

{"status":"ok"}

200Encaminhado a um destino externo

json

{"status":"routed"}

Outros 200: {"status":"forward_failed"} (o destino externo falhou), {"status":"ignored"} (nenhuma loja dona do número) e {"status":"process_error"}.

Erros

Status	Quando	Corpo
400	Não foi possível ler o corpo	`{"error":"failed to read body"}`
401	Assinatura inválida	`{"error":"invalid signature"}`
403	Segredo do app não cadastrado	`{"error":"app secret not configured"}`
503	Credenciais da plataforma indisponíveis, ou limite de 20 segundos excedido	`{"error":"platform credentials unavailable"}`

Contrato de quem recebe o encaminhamento

Quando a rota do número aponta para um sistema seu, a plataforma faz um POST na webhook_url cadastrada com o mesmo corpo recebido da Meta e estes cabeçalhos:

Cabeçalho	Valor
`Content-Type`	`application/json`
`X-Route-Name`	Nome da rota
`X-Business-Phone`	Número comercial, só dígitos, com DDI
`X-Route-Key` e `X-Route-Api-Key`	Chave própria da rota, para o seu servidor reconhecer a origem

Responda 2xx em até 12 segundos. Outro status ou demora é registrado como falha de encaminhamento e não é repetido pela plataforma.

Cadastrar uma rota

POST/api/v1/webhooks/whatsapp-routes/registerPública

Cadastrar ou atualizar a rota de um número

Cabeçalhos

X-Api-Keystringobrigatório

Chave mestra de rotas. Também aceita no parâmetro de consulta api_key.

Corpo da requisição

namestringobrigatório

Nome da rota, para você reconhecê-la.

phone_numberstringobrigatório

Número comercial brasileiro. Aceita máscara; o DDI 55 é acrescentado se faltar. Entre 12 e 15 dígitos no total.

webhook_urlstring

URL que receberá as notificações do número. Se omitida, usa o destino padrão da plataforma.

verify_tokenstring

Token de verificação desta rota. Se omitido, a plataforma usa um padrão.

activebooleanpadrão: true

false desativa a rota sem apagá-la.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/webhooks/whatsapp-routes/register" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $ROUTES_MASTER_KEY" \
  -d '{"name":"Loja Centro","phone_number":"(11) 4004-1234","webhook_url":"https://api.minhaempresa.example.com/whatsapp/inbound","active":true}'

Resposta

200Rota registrada

json

{
  "success": true,
  "message": "Route registered successfully",
  "data": {
    "route_id": 17,
    "name": "Loja Centro",
    "phone_number": "551140041234",
    "webhook_url": "https://api.minhaempresa.example.com/whatsapp/inbound",
    "verify_token": "meu-token-de-verificacao",
    "api_key": "rk_live_example_not_real",
    "active": true,
    "created_at": "2026-10-11T20:30:00Z",
    "updated_at": "2026-10-11T20:30:00Z"
  }
}

Campos da resposta

successboolean

true quando registrou.

messagestring

Mensagem em inglês.

dataobject

A rota.

route_idinteger

Id numérico da rota.

namestring

Nome.

phone_numberstring

Número normalizado, só dígitos, com DDI.

webhook_urlstring

Destino das notificações.

verify_tokenstring

Token de verificação da rota.

api_keystring

Chave própria da rota, enviada em X-Route-Key ao encaminhar. Guarde-a para reconhecer a origem.

activeboolean

Se a rota está ativa.

created_atstring

Criação, RFC 3339.

updated_atstring

Última alteração, RFC 3339.

Erros

Status	Quando	Corpo
400	Corpo inválido	`{"success":false,"message":"Invalid request body","data":null}`
400	`name` ausente ou telefone fora do formato	`{"success":false,"message":"name is required","data":null}`
401	Sem chave de API	`{"success":false,"message":"API key required","data":null}`
403	Chave de API inválida	`{"success":false,"message":"Invalid API key","data":null}`