Skip to main content
O corpo da requisição segue sempre esta estrutura padrão, facilitando a tipagem no seu backend: 
{
  "event": "message.read",
  "workspace_id": "ws_123456...",
  "instance_id": "inst_abc789...",
  "message_id": "msg_xyz000...",
  "timestamp": "2025-02-10T14:30:00.000Z",
  "data": {
    "to": "5511999999999",
    "status": "READ",
    "externalId": "wamid.HBgM..."
  }
}
O campo data varia ligeiramente dependendo do evento, mas os campos de identificação (event, ids, timestamp) são constantes.

​
Tabela de Eventos (Escopos)

Ao configurar um Webhook no painel, você escolhe quais eventos deseja ouvir. Para evitar ruído desnecessário no seu servidor, ative apenas o que for útil para sua aplicação.

​
Eventos de Mensagem (Ciclo de Vida)

  • message.sent A mensagem saiu da nossa fila e foi aceita pelos servidores da Meta. (1 tique cinza).
  • message.delivered O aparelho do destinatário recebeu a notificação. (2 tiques cinzas).
  • message.read O destinatário abriu a conversa ou deu play no áudio. (2 tiques azuis).
  • message.failed Ocorreu um erro (número inválido, bloqueio ou falha técnica) após todas as tentativas.
  • message.received Seu número recebeu uma mensagem de texto, áudio ou mídia (Inbound). Ideal para Chatbots.
  • message.responded O destinatário usou a função “Responder” (Swipe right) em uma mensagem sua específica.
  • message.deleted A mensagem foi apagada (“Apagar para todos”) pelo remetente ou via API.
  • message.edited O conteúdo do texto foi alterado após o envio.

​
Eventos de Instância (Conectividade)

  • instance.connected A leitura do QR Code foi bem-sucedida ou a sessão foi restaurada automaticamente.
  • instance.disconnected O celular ficou sem bateria, sem internet ou o usuário encerrou a sessão no aparelho.
  • instance.qrcode Um novo código foi gerado e precisa ser escaneado. O payload contém o base64 da imagem.

​
Segurança e Validação (Headers)

Como garantir que o POST veio da Zenvio e não de um hacker? Nós enviamos headers de assinatura em todas as requisições de webhook.
  • X-Zenvio-Signature Hash HMAC-SHA256 do corpo da requisição, assinado com seu Segredo de Webhook. Formato: t=timestamp,v1=hash.
  • X-Zenvio-Timestamp O momento exato (Unix Timestamp) em que geramos o evento. Use para evitar Replay Attacks.
  • X-Workspace-Id O ID do workspace, para facilitar o roteamento em sistemas multi-tenant.
Dica de Segurança: Sempre verifique se o timestamp é recente (ex: menos de 5 minutos) e recalcule o hash para validar a origem.

​
Respostas Esperadas

O seu servidor deve responder à nossa requisição o mais rápido possível para evitar timeouts.
  • Status 2xx Sucesso. O evento é marcado como entregue e sai da nossa fila.
  • Status 4xx / 5xx / timeout Falha. Nós agendamos uma retentativa automática.
Importante: Se o seu processamento for demorado (ex: gerar um relatório complexo ao receber uma mensagem), responda 200 OK imediatamente e processe a lógica em background (background job). Se você demorar mais de 10 segundos, nós consideraremos Timeout e enviaremos de novo.