Eventos dos Webhooks

Na API você pergunta; no webhook a Notifique avisa. É como o app do banco mandando push quando o PIX cai, seu backend não precisa ficar consultando a cada segundo.

Em poucas palavras

Toda entrega é um POST application/json para a URL que você cadastrou.
Eventos message.* e instance.* são só WhatsApp (Telegram usa telegram.*).
Ative só os eventos que sua integração usa.
Responda 2xx rápido; trabalho pesado vai para fila no seu lado.

Configuração geral: Webhooks. Segurança (assinatura HMAC): Segurança de webhooks.

Como vem o POST

Estrutura padrão em todos os eventos:

{
  "event": "message.read",
  "workspaceId": "clxxworkspace123",
  "instanceId": "clxxinstance456",
  "messageId": "clxxmessage789",
  "timestamp": "2025-02-20T14:06:00.000Z",
  "data": {
    "to": "5511999999999",
    "status": "READ"
  }
}

Campo	Descrição
`event`	Nome do evento (ex.: `message.sent`)
`workspaceId`	ID do workspace
`instanceId`	ID da instância WhatsApp
`messageId`	ID da mensagem enviada (quando aplicável)
`timestamp`	ISO 8601, use para anti-replay
`data`	Campos específicos do evento (camelCase)

Headers: X-Notifique-Signature, X-Notifique-Timestamp, X-Workspace-Id.

O que seu servidor deve responder

Resposta	Efeito
2xx em até ~10s	Evento entregue; sai da fila
4xx / 5xx / timeout	Retentativa automática (5 min, 30 min, 2 h)

Processamento demorado? Responda 200 logo e processe em background. Demorar mais de 10 segundos conta como timeout e o evento pode ser reenviado.

Valide X-Notifique-Signature e timestamp recente. Detalhes: Segurança de webhooks.

Referência por evento

Use estes eventos ao integrar bot, atendimento, ERP ou automação no WhatsApp.

Os nomes message.* são só WhatsApp. Telegram usa telegram.*: eventos Telegram.

Mensagens que você envia

Evento	Quando dispara	O que fazer com isso
`message.sent`	Mensagem aceita e enviada (✓ cinza)	Marcar como “enviado” no seu sistema
`message.delivered`	Chegou no aparelho do cliente (✓✓ cinza)	Confirmar entrega
`message.read`	Cliente leu ou ouviu (✓✓ azul)	Métricas, follow-up
`message.clicked`	Cliente clicou em link curto do envio	Rastrear campanha
`message.failed`	Não deu para enviar (número inválido, instância off…)	Alertar, retentar ou cancelar pedido
`message.deleted`	Mensagem apagada “para todos”	Atualizar histórico
`message.edited`	Texto alterado após envio	Sincronizar conteúdo
`message.updated`	Qualquer mudança de status	Webhook genérico de status
`message.cancelled`	Agendamento cancelado	Liberar slot / avisar equipe
`message.responded`	Cliente respondeu citando sua mensagem	Atendimento, bot conversacional

Mensagens que você recebe

Evento	Quando dispara	O que fazer com isso
`whatsapp.received`	Alguém te mandou WhatsApp	Bot, ticket, CRM, o mais usado para inbound
`whatsapp.inbound.edited`	Cliente editou msg que você guardou	Atualizar conversa
`whatsapp.inbound.deleted`	Cliente apagou msg recebida	Remover ou marcar no histórico

Inbound só dispara se estiver ligado em Settings → Received messages (guardar e/ou webhook). O nome antigo message.received no painel ainda funciona: o corpo vem como whatsapp.received.

Instância (conexão do número)

Evento	Quando dispara	O que fazer com isso
`instance.connecting`	Aguardando escaneamento do código	Mostrar “escaneie o código”
`instance.qrcode`	Novo código gerado	Exibir QR na sua UI (`data.base64`)
`instance.connected`	Número conectou	Liberar envios, avisar equipe
`instance.disconnected`	Desconectou (celular off, logout…)	Pausar campanhas, alertar NOC

No Quick Start, renovar código pode usar este webhook em vez de polling (instance.qrcode).

Payload de cada evento

Corpo completo (body) do POST. O envelope (event, ids, timestamp) é igual ao exemplo acima; abaixo, o que muda em data.

message.sent

{
  "event": "message.sent",
  "workspaceId": "clxxworkspace123",
  "instanceId": "clxxinstance456",
  "messageId": "clxxmessage789",
  "timestamp": "2025-02-20T14:05:00.000Z",
  "data": {
    "to": "5511999999999",
    "type": "TEXT",
    "status": "SENT",
    "sentAt": "2025-02-20T14:05:00.000Z",
    "externalId": "3EB0xxxx"
  }
}

message.delivered

{
  "event": "message.delivered",
  "workspaceId": "clxxworkspace123",
  "instanceId": "clxxinstance456",
  "messageId": "clxxmessage789",
  "timestamp": "2025-02-20T14:05:30.000Z",
  "data": {
    "messageId": "clxxmessage789",
    "to": "5511999999999",
    "status": "DELIVERED"
  }
}

message.read

{
  "event": "message.read",
  "workspaceId": "clxxworkspace123",
  "instanceId": "clxxinstance456",
  "messageId": "clxxmessage789",
  "timestamp": "2025-02-20T14:06:00.000Z",
  "data": {
    "messageId": "clxxmessage789",
    "to": "5511999999999",
    "status": "READ"
  }
}

message.clicked

Disparado no primeiro clique em link curto do envio (workspace com links curtos ligados).

{
  "event": "message.clicked",
  "workspaceId": "clxxworkspace123",
  "instanceId": "clxxinstance456",
  "messageId": "clxxmessage789",
  "timestamp": "2025-02-20T14:06:30.000Z",
  "data": {
    "messageId": "clxxmessage789",
    "to": "5511999999999",
    "status": "CLICKED",
    "clickedAt": "2025-02-20T14:06:30.000Z"
  }
}

message.failed

{
  "event": "message.failed",
  "workspaceId": "clxxworkspace123",
  "instanceId": "clxxinstance456",
  "messageId": "clxxmessage789",
  "timestamp": "2025-02-20T14:05:00.000Z",
  "data": {
    "messageId": "clxxmessage789",
    "to": "5511999999999",
    "status": "FAILED",
    "reason": "instance_disconnected"
  }
}

whatsapp.received

{
  "event": "whatsapp.received",
  "workspaceId": "clxxworkspace123",
  "instanceId": "clxxinstance456",
  "timestamp": "2025-02-20T14:10:00.000Z",
  "data": {
    "persisted": true,
    "inboundId": "clxxinbound001",
    "from": "5511999999999",
    "bodyPreview": "Olá!",
    "remoteJid": "5511999999999@s.whatsapp.net",
    "isGroup": false,
    "externalMessageId": "3EB0xxxx",
    "matchedRuleIds": [],
    "persistDeniedReason": null,
    "storageCreditsCharged": 1,
    "storageCentsCharged": 0
  }
}

Campos extras podem ser adicionados sem quebrar consumidores.

message.responded

{
  "event": "message.responded",
  "workspaceId": "clxxworkspace123",
  "instanceId": "clxxinstance456",
  "messageId": "clxxmessage789",
  "timestamp": "2025-02-20T14:10:00.000Z",
  "data": {
    "messageId": "clxxmessage789",
    "replyText": "Resposta do destinatário",
    "status": "RESPONDED"
  }
}

message.deleted

{
  "event": "message.deleted",
  "workspaceId": "clxxworkspace123",
  "instanceId": "clxxinstance456",
  "messageId": "clxxmessage789",
  "timestamp": "2025-02-20T14:07:00.000Z",
  "data": {
    "messageId": "clxxmessage789",
    "to": "5511999999999",
    "status": "DELETED",
    "source": "api"
  }
}

message.edited

{
  "event": "message.edited",
  "workspaceId": "clxxworkspace123",
  "instanceId": "clxxinstance456",
  "messageId": "clxxmessage789",
  "timestamp": "2025-02-20T14:08:00.000Z",
  "data": {
    "messageId": "clxxmessage789",
    "to": "5511999999999",
    "status": "EDITED",
    "newContent": "Texto corrigido"
  }
}

newContent pode ser null quando não disponível.

message.updated

{
  "event": "message.updated",
  "workspaceId": "clxxworkspace123",
  "instanceId": "clxxinstance456",
  "messageId": "clxxmessage789",
  "timestamp": "2025-02-20T14:06:15.000Z",
  "data": {
    "messageId": "clxxmessage789",
    "to": "5511999999999",
    "status": "DELIVERED",
    "previousStatus": "SENT"
  }
}

message.cancelled

{
  "event": "message.cancelled",
  "workspaceId": "clxxworkspace123",
  "instanceId": "clxxinstance456",
  "messageId": "clxxmessage789",
  "timestamp": "2025-02-20T14:04:00.000Z",
  "data": {
    "messageId": "clxxmessage789",
    "to": "5511999999999",
    "status": "CANCELLED"
  }
}

whatsapp.inbound.edited

{
  "event": "whatsapp.inbound.edited",
  "workspaceId": "clxxworkspace123",
  "instanceId": "clxxinstance456",
  "timestamp": "2025-02-20T14:11:00.000Z",
  "data": {
    "inboundId": "clxxinbound001",
    "from": "5511999999999",
    "bodyPreview": "Olá! (editado)",
    "externalMessageId": "3EB0yyyy"
  }
}

whatsapp.inbound.deleted

{
  "event": "whatsapp.inbound.deleted",
  "workspaceId": "clxxworkspace123",
  "instanceId": "clxxinstance456",
  "timestamp": "2025-02-20T14:12:00.000Z",
  "data": {
    "inboundId": "clxxinbound001",
    "from": "5511999999999",
    "externalMessageId": "3EB0yyyy"
  }
}

instance.qrcode

{
  "event": "instance.qrcode",
  "workspaceId": "clxxworkspace123",
  "instanceId": "clxxinstance456",
  "timestamp": "2025-02-20T14:00:00.000Z",
  "data": {
    "base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
  }
}

instance.connected

{
  "event": "instance.connected",
  "workspaceId": "clxxworkspace123",
  "instanceId": "clxxinstance456",
  "timestamp": "2025-02-20T14:01:00.000Z",
  "data": {
    "phoneNumber": "5511999999999"
  }
}

phoneNumber pode ser null em alguns casos.

instance.disconnected

{
  "event": "instance.disconnected",
  "workspaceId": "clxxworkspace123",
  "instanceId": "clxxinstance456",
  "timestamp": "2025-02-20T14:02:00.000Z",
  "data": {}
}

instance.connecting

{
  "event": "instance.connecting",
  "workspaceId": "clxxworkspace123",
  "instanceId": "clxxinstance456",
  "timestamp": "2025-02-20T14:00:00.000Z",
  "data": {
    "status": "AWAITING_QR",
    "message": "QR code generated; scan to connect"
  }
}

Próximos passos

Quick Start: conectar e enviar
Escopos da API Key: permissões para ler inbound
Webhooks (guia): criar endpoint e testar

​Em poucas palavras

​Como vem o POST

​O que seu servidor deve responder

​Referência por evento

​Mensagens que você envia

​Mensagens que você recebe

​Instância (conexão do número)

​Payload de cada evento

​Próximos passos

Em poucas palavras

Como vem o POST

O que seu servidor deve responder

Referência por evento

Mensagens que você envia

Mensagens que você recebe

Instância (conexão do número)

Payload de cada evento

Próximos passos