Webhooks de status

Receba no seu sistema o status das mensagens do WhatsApp.

Configure uma URL para receber eventos padronizados de criação, entrega, leitura e erro e consulte o histórico das entregas pela API, independentemente da conexão escolhida.

Configurar no painel Ver Events API

Webhook POST https://seusistema.com/webhooks/wpp

{
  "id": "evt_0123456789abcdef",
  "event": "MESSAGE_DELIVERED",
  "timestamp": "2026-09-15T10:30:00Z",
  "message": {
    "id": "msg_123",
    "status": "delivered",
    "phone": "5511999999999"
  }
}

Fluxo

O WPP Marketing avisa seu sistema quando o status muda.

Webhooks de status são úteis para auditoria, conciliação, dashboards internos, suporte e regras do seu próprio sistema.

01 Você informa a URL

Cadastre no painel um endpoint HTTPS do seu sistema para receber os retornos.

02 Escolhe os eventos

Ative apenas os status que seu sistema precisa consumir para evitar ruído operacional.

03 Status muda

Criação, entrega, leitura ou erro são normalizados da mesma maneira, independentemente da conexão escolhida.

04 Receba e acompanhe

Seu endpoint processa o payload e o histórico de entregas fica disponível no painel e em GET /webhooks.

Eventos disponíveis e consulta das entregas.

Os quatro eventos usam o mesmo contrato em qualquer conexão, e a API permite consultar o resultado de cada tentativa de entrega.

POST MESSAGE_CREATED

Mensagem foi criada no fluxo e recebeu identificador para acompanhamento.

Criação

POST MESSAGE_DELIVERED

Mensagem foi entregue ao destino quando o canal retorna confirmação.

Entrega

POST MESSAGE_READ

Mensagem foi lida, quando a confirmação de leitura está disponível.

Leitura

POST MESSAGE_ERROR

Mensagem encontrou erro de envio, validação ou processamento.

Erro

GET /webhooks

Consulta o histórico de entregas com status, tentativas, resposta HTTP e paginação. Requer o escopo webhooks:read.

Logs

Boas práticas

Prepare seu endpoint para receber eventos repetidos e fora de ordem.

Webhooks são entregas entre sistemas. Seu backend deve responder rápido, registrar logs e processar com idempotência.

HTTPS

Use URL segura, pública e estável para receber os eventos de retorno.

Resposta rápida

Responda HTTP 200 ou 204 após receber o evento e processe tarefas demoradas em fila interna.

Idempotência

Use identificadores de mensagem e evento para evitar duplicidade em reentregas.

Logs

Registre payload, data, status HTTP e resultado do processamento para auditoria.

Alertas

Use MESSAGE_ERROR para alertar suporte ou operação sobre falhas retornadas por qualquer conexão.

Separação

Webhooks de status são retorno do WPP Marketing. Para enviar eventos comerciais da loja, use Events API.

Quer acompanhar entregas e erros no seu sistema?

Configure uma URL no painel, escolha os status e acompanhe as entregas no relatório de webhooks.

Configurar webhooks