Introdução

1. Formato geral do payload

Todas as requisições são POST com Content-Type: application/json. O corpo segue a estrutura:

{
  "event": "message.sent",
  "workspaceId": "clxx...",
  "instanceId": "clxx...",
  "messageId": "clxx...",
  "timestamp": "2025-02-09T12:00:00.000Z",
  "data": { ... }
}

Campo	Tipo	Descrição
event	string	Nome do evento (ex.: `message.sent`, `sms.delivered`).
workspace_id	string	ID do workspace.
instanceId	string	ID da instância WhatsApp (vazio para SMS, e-mail e push).
message_id	string \| undefined	ID da mensagem no Notifique (quando aplicável).
timestamp	string	ISO 8601; use para anti-replay (janela recomendada: 5 min).
data	object	Dados específicos do evento (ver por canal abaixo).

2. Headers e assinatura

Header	Descrição
Content-Type	`application/json`
X-Webhook-Event	Nome do evento.
X-Notifique-Timestamp	Timestamp em segundos (Unix) usado na assinatura.
X-Notifique-Signature	Assinatura: `t={timestamp},v1={hash}`.
X-Workspace-Id	ID do workspace.

Cálculo HMAC: hash = HMAC-SHA256(secret, timestamp + "." + body) (body = corpo bruto do POST).
Anti-replay: Rejeite requisições com timestamp fora de uma janela (ex.: 5 minutos).

3. Por canal

3.1 WhatsApp — Mensagens e instância

Escopos disponíveis

Escopo	Descrição	Quando é disparado
message.sent	Mensagem enviada foi aceita.	Após envio bem-sucedido.
message.delivered	Mensagem entregue no dispositivo.	Provedor envia DELIVERY_ACK.
message.read	Mensagem foi lida (ou mídia tocada).	Provedor envia READ/PLAYED.
message.failed	Falha no envio.	Worker falha ou provedor envia ERROR.
message.deleted	Mensagem deletada (“apagar para todos”).	Provedor ou API/app.
message.edited	Mensagem de texto editada.	Provedor ou API/app.
message.updated	Qualquer atualização de status.	Em toda mudança (sent, delivered, read, etc.).
message.cancelled	Mensagem agendada cancelada.	API ou app.
message.received	Mensagem recebida (inbound).	WhatsApp: quando a mensagem inbound é persistida. SMS usa `sms.received` / `sms.replied`.
message.responded	Destinatário respondeu (reply).	Provedor (reply).
instance.connected	Instância conectada ao WhatsApp.	QR lido ou sessão restaurada.
instance.disconnected	Instância desconectada.	Provedor (connection.update close).
instance.qrcode	Novo QR code para pareamento.	Provedor (qrcode.updated).
instance.connecting	Instância aguardando QR.	Provedor (qrcode) quando não ACTIVE.

Retorno completo por evento

instance.qrcode

data	Tipo	Descrição
base64	string	Imagem do QR em base64.

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

instance.connected

data	Tipo	Descrição
phone_number	string \| null	Número do WhatsApp conectado.

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

instance.disconnected

data	Descrição
(objeto vazio)	`{}`

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

instance.connecting

data	Tipo	Descrição
status	string	`"AWAITING_QR"`.
message	string	Mensagem descritiva.

{
  "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"
  }
}

message.sent

data	Tipo	Descrição
to	string	Destinatário (E.164).
type	string	Tipo (TEXT, IMAGE, etc.).
status	string	`"SENT"`.
sent_at	string	ISO 8601.
external_id	string	ID no provedor.

{
  "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

data	Tipo	Descrição
message_id	string	ID da mensagem no Notifique.
to	string	Destinatário.
status	string	`"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

data	Tipo	Descrição
message_id	string	ID da mensagem.
to	string	Destinatário.
status	string	`"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.failed

data	Tipo	Descrição
message_id	string	Opcional.
to	string	Destinatário.
status	string	`"FAILED"`.
reason	string	Motivo (ex.: instance_disconnected).

{
  "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"
  }
}

message.deleted

data	Tipo	Descrição
message_id	string	ID da mensagem.
to	string	Destinatário.
status	string	`"DELETED"`.
source	string	`"messages.delete"`, `"revoke"` ou `"api"`.

{
  "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

data	Tipo	Descrição
message_id	string	ID da mensagem.
to	string	Destinatário.
status	string	`"EDITED"`.
new_content	string \| null	Novo texto.

{
  "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 atualizado"
  }
}

message.updated

data	Tipo	Descrição
message_id	string	ID da mensagem.
to	string	Destinatário.
status	string	Novo status (SENT, DELIVERED, READ, FAILED, etc.).
previous_status	string	Status anterior.
reason	string \| null	Motivo (ex.: em falha).

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

message.cancelled

data	Tipo	Descrição
message_id	string	ID da mensagem.
to	string	Destinatário.
status	string	`"CANCELLED"`.

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

message.received

data	Tipo	Descrição
from	string	Remetente.
type	string	Tipo (text, etc.).
content	string	Conteúdo.
status	string	`"RECEIVED"`.

{
  "event": "message.received",
  "workspaceId": "clxxworkspace123",
  "instanceId": "clxxinstance456",
  "messageId": "clxxinbound001",
  "timestamp": "2025-02-20T14:10:00.000Z",
  "data": {
    "from": "5511999999999",
    "type": "text",
    "content": "Olá!",
    "status": "RECEIVED"
  }
}

message.responded

data	Tipo	Descrição
message_id	string	ID da mensagem respondida.
reply_text	string	Texto da resposta.
status	string	`"RESPONDED"`.

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

3.2 SMS

instanceId vem vazio em todos os eventos SMS.

Escopos disponíveis

Escopo	Descrição	Quando é disparado
sms.sent	SMS aceito e enviado.	Após envio bem-sucedido.
sms.delivered	SMS entregue (DLR).	Callback do provedor.
sms.failed	SMS falhou.	Falha no envio ou DLR de erro.
sms.cancelled	SMS agendado cancelado.	API ou app (POST cancel).
sms.received	SMS de entrada (MO) persistido.	Callback MO do provedor configurado na integração.
sms.replied	Resposta vinculada a um envio.	MO correlacionado a um `smsId` de saída.

Retorno completo por evento

sms.sent

data	Tipo	Descrição
smsId	string	ID do SMS no Notifique.
to	string	Destinatário (E.164).
status	string	`"SENT"`.
sent_at	string	ISO 8601.
external_id	string \| undefined	ID no provedor.
provider	string \| undefined	Nome do provedor.

{
  "event": "sms.sent",
  "workspaceId": "clxxworkspace123",
  "instanceId": "",
  "timestamp": "2025-02-20T14:00:00.000Z",
  "data": {
    "smsId": "clxxsms123",
    "to": "5511999999999",
    "status": "SENT",
    "sentAt": "2025-02-20T14:00:00.000Z",
    "externalId": "provider-msg-123"
  }
}

sms.delivered

data	Tipo	Descrição
smsId	string	ID do SMS.
to	string	Destinatário.
status	string	`"DELIVERED"`.
deliveredAt	string	ISO 8601.

{
  "event": "sms.delivered",
  "workspaceId": "clxxworkspace123",
  "instanceId": "",
  "timestamp": "2025-02-20T14:00:30.000Z",
  "data": {
    "smsId": "clxxsms123",
    "to": "5511999999999",
    "status": "DELIVERED",
    "deliveredAt": "2025-02-20T14:00:30.000Z"
  }
}

sms.failed

data	Tipo	Descrição
smsId	string	ID do SMS.
to	string	Destinatário.
status	string	`"FAILED"`.
failedAt	string	ISO 8601.

{
  "event": "sms.failed",
  "workspaceId": "clxxworkspace123",
  "instanceId": "",
  "timestamp": "2025-02-20T14:00:00.000Z",
  "data": {
    "smsId": "clxxsms123",
    "to": "5511999999999",
    "status": "FAILED",
    "failedAt": "2025-02-20T14:00:00.000Z"
  }
}

sms.cancelled

data	Tipo	Descrição
smsId	string	ID do SMS.
to	string	Destinatário.
status	string	`"CANCELLED"`.

{
  "event": "sms.cancelled",
  "workspaceId": "clxxworkspace123",
  "instanceId": "",
  "timestamp": "2025-02-20T14:00:00.000Z",
  "data": {
    "smsId": "clxxsms123",
    "to": "5511999999999",
    "status": "CANCELLED"
  }
}

sms.received

data	Tipo	Descrição
inboundId	string	ID do registro de SMS recebido.
from	string	Remetente do MO.
body	string	Texto recebido.
provider	string	Identificador do canal no provedor (valor depende da integração).
relatedSmsId	string \| null	Envio original, se correlacionado.
externalMoId	string	ID do MO no provedor.

sms.replied Mesmos campos que sms.received, com smsId (envio original) obrigatório em data quando o MO está vinculado.

3.3 E-mail

instanceId vem vazio em todos os eventos de e-mail.

Escopos disponíveis

Escopo	Descrição	Quando é disparado
email.sent	E-mail aceito e enviado.	Após envio bem-sucedido (worker).
email.delivered	E-mail entregue.	Callback do provedor.
email.opened	E-mail aberto pelo destinatário (open tracking).	Primeira abertura (callback do provedor).
email.clicked	Link do e-mail clicado (click tracking).	Clique em link rastreado (callback do provedor).
email.failed	E-mail falhou ou bounce.	Falha no worker ou callback.
email.complained	Reclamação de spam.	Callback do provedor (complaint).
email.cancelled	E-mail agendado cancelado.	API ou app (POST cancel).

Retorno completo por evento

email.sent

data	Tipo	Descrição
emailId	string	ID do e-mail no Notifique.
to	string[]	Destinatários.
from	string	Remetente.
status	string	`"SENT"`.
sentAt	string	ISO 8601.

{
  "event": "email.sent",
  "workspaceId": "clxxworkspace123",
  "instanceId": "",
  "timestamp": "2025-02-20T14:00:00.000Z",
  "data": {
    "emailId": "clxxemail123",
    "to": ["cliente@example.com"],
    "from": "noreply@seudominio.com",
    "status": "SENT",
    "sentAt": "2025-02-20T14:00:00.000Z"
  }
}

email.delivered

data	Tipo	Descrição
emailId	string	ID do e-mail.
to	string[]	Destinatários.
from	string	Remetente.
status	string	`"DELIVERED"`.

{
  "event": "email.delivered",
  "workspaceId": "clxxworkspace123",
  "instanceId": "",
  "timestamp": "2025-02-20T14:00:05.000Z",
  "data": {
    "emailId": "clxxemail123",
    "to": ["cliente@example.com"],
    "from": "noreply@seudominio.com",
    "status": "DELIVERED"
  }
}

email.opened

data	Tipo	Descrição
emailId	string	ID do e-mail.
to	string	Destinatário.
from	string	Remetente.
status	string	`"OPENED"`.
openedAt	string	ISO 8601; primeira abertura.

{
  "event": "email.opened",
  "workspaceId": "clxxworkspace123",
  "instanceId": "",
  "timestamp": "2025-02-20T14:00:30.000Z",
  "data": {
    "emailId": "clxxemail123",
    "to": "cliente@example.com",
    "from": "noreply@seudominio.com",
    "status": "OPENED",
    "openedAt": "2025-02-20T14:00:30.000Z"
  }
}

email.clicked

data	Tipo	Descrição
emailId	string	ID do e-mail.
to	string	Destinatário.
from	string	Remetente.
status	string	`"CLICKED"`.
clickedAt	string	ISO 8601; primeiro clique em link.

{
  "event": "email.clicked",
  "workspaceId": "clxxworkspace123",
  "instanceId": "",
  "timestamp": "2025-02-20T14:00:45.000Z",
  "data": {
    "emailId": "clxxemail123",
    "to": "cliente@example.com",
    "from": "noreply@seudominio.com",
    "status": "CLICKED",
    "clickedAt": "2025-02-20T14:00:45.000Z"
  }
}

email.failed

data	Tipo	Descrição
emailId	string	ID do e-mail.
to	string[]	Destinatários.
from	string	Remetente.
status	string	`"FAILED"`.
error	string	Mensagem de erro.

{
  "event": "email.failed",
  "workspaceId": "clxxworkspace123",
  "instanceId": "",
  "timestamp": "2025-02-20T14:00:00.000Z",
  "data": {
    "emailId": "clxxemail123",
    "to": ["cliente@example.com"],
    "from": "noreply@seudominio.com",
    "status": "FAILED",
    "error": "Invalid address"
  }
}

email.complained

data	Tipo	Descrição
emailId	string	ID do e-mail.
to	string	Destinatário.
from	string	Remetente.
status	string	`"COMPLAINED"`.

{
  "event": "email.complained",
  "workspaceId": "clxxworkspace123",
  "instanceId": "",
  "timestamp": "2025-02-20T14:00:10.000Z",
  "data": {
    "emailId": "clxxemail123",
    "to": "cliente@example.com",
    "from": "noreply@seudominio.com",
    "status": "COMPLAINED"
  }
}

email.cancelled

data	Tipo	Descrição
emailId	string	ID do e-mail.
to	string	Destinatário.
from	string	Remetente.
status	string	`"CANCELLED"`.

{
  "event": "email.cancelled",
  "workspaceId": "clxxworkspace123",
  "instanceId": "",
  "timestamp": "2025-02-20T14:00:00.000Z",
  "data": {
    "emailId": "clxxemail123",
    "to": "cliente@example.com",
    "from": "noreply@seudominio.com",
    "status": "CANCELLED"
  }
}

3.4 Push

instanceId vem vazio em todos os eventos de push. Dados vão em data (pushId, deviceId, appId, status, etc.).

Escopos disponíveis

Escopo	Descrição	Quando é disparado
push.sent	Push aceito e enviado.	Após envio bem-sucedido (worker).
push.delivered	Push entregue no dispositivo.	SW/navegador reporta via POST /v1/push/events/delivered.
push.clicked	Usuário clicou na notificação.	Cliente reporta via POST /v1/push/events/click.
push.failed	Push falhou no envio.	Falha no worker (subscription inválida, etc.).
push.cancelled	Push agendado cancelado.	API ou app (POST cancel).

Retorno completo por evento

push.sent

data	Tipo	Descrição
pushId	string	ID do push no Notifique.
deviceId	string	ID do dispositivo (subscription).
appId	string	ID do app de push.
status	string	`"SENT"`.

{
  "event": "push.sent",
  "workspaceId": "clxxworkspace123",
  "instanceId": "",
  "timestamp": "2025-02-20T14:00:00.000Z",
  "data": {
    "pushId": "clxxpush123",
    "deviceId": "clxxdevice456",
    "appId": "clxxapp789",
    "status": "SENT"
  }
}

push.delivered

data	Tipo	Descrição
pushId	string	ID do push.
deviceId	string	ID do dispositivo.
appId	string	ID do app.
status	string	`"DELIVERED"`.
deliveredAt	string	Data/hora da entrega (ISO 8601).

{
  "event": "push.delivered",
  "workspaceId": "clxxworkspace123",
  "instanceId": "",
  "timestamp": "2025-02-20T14:00:05.000Z",
  "data": {
    "pushId": "clxxpush123",
    "deviceId": "clxxdevice456",
    "appId": "clxxapp789",
    "status": "DELIVERED",
    "deliveredAt": "2025-02-20T14:00:05.000Z"
  }
}

push.clicked

data	Tipo	Descrição
pushId	string	ID do push.
deviceId	string	ID do dispositivo.
appId	string	ID do app.
status	string	`"CLICKED"`.
clickedAt	string	Data/hora do clique (ISO 8601).

{
  "event": "push.clicked",
  "workspaceId": "clxxworkspace123",
  "instanceId": "",
  "timestamp": "2025-02-20T14:00:05.000Z",
  "data": {
    "pushId": "clxxpush123",
    "deviceId": "clxxdevice456",
    "appId": "clxxapp789",
    "status": "CLICKED",
    "clickedAt": "2025-02-20T14:00:05.123Z"
  }
}

push.failed

data	Tipo	Descrição
pushId	string	ID do push.
deviceId	string	ID do dispositivo.
appId	string	ID do app.
status	string	`"FAILED"`.
error	string	Mensagem de erro.

{
  "event": "push.failed",
  "workspaceId": "clxxworkspace123",
  "instanceId": "",
  "timestamp": "2025-02-20T14:00:00.000Z",
  "data": {
    "pushId": "clxxpush123",
    "deviceId": "clxxdevice456",
    "appId": "clxxapp789",
    "status": "FAILED",
    "error": "Subscription expired"
  }
}

push.cancelled

data	Tipo	Descrição
pushId	string	ID do push.
deviceId	string	ID do dispositivo.
appId	string	ID do app.
status	string	`"CANCELLED"`.

{
  "event": "push.cancelled",
  "workspaceId": "clxxworkspace123",
  "instanceId": "",
  "timestamp": "2025-02-20T14:00:00.000Z",
  "data": {
    "pushId": "clxxpush123",
    "deviceId": "clxxdevice456",
    "appId": "clxxapp789",
    "status": "CANCELLED"
  }
}

4. Comportamento do worker de webhooks

Eventos são enfileirados.
Timeout por requisição: 10 s. Retentativas: 5 min, 30 min, 2 h (até 4 tentativas).
Após 4 falhas consecutivas, o webhook pode ser marcado como failing.

Simples assim

Construa com IA

BYOK

API Key

Logs

Webhooks

Workspaces

Introdução

1. Formato geral do payload

2. Headers e assinatura

3. Por canal

3.1 WhatsApp — Mensagens e instância

Escopos disponíveis

Retorno completo por evento

3.2 SMS

Escopos disponíveis

Retorno completo por evento

3.3 E-mail

Escopos disponíveis

Retorno completo por evento

3.4 Push

Escopos disponíveis

Retorno completo por evento

4. Comportamento do worker de webhooks

Introdução

Simples assim

Construa com IA

BYOK

API Key

Logs

Webhooks

Workspaces

​1. Formato geral do payload

​2. Headers e assinatura

​3. Por canal

​3.1 WhatsApp — Mensagens e instância

​Escopos disponíveis

​Retorno completo por evento

​3.2 SMS

​Escopos disponíveis

​Retorno completo por evento

​3.3 E-mail

​Escopos disponíveis

​Retorno completo por evento

​3.4 Push

​Escopos disponíveis

​Retorno completo por evento

​4. Comportamento do worker de webhooks

1. Formato geral do payload

2. Headers e assinatura

3. Por canal

3.1 WhatsApp — Mensagens e instância

Escopos disponíveis

Retorno completo por evento

3.2 SMS

Escopos disponíveis

Retorno completo por evento

3.3 E-mail

Escopos disponíveis

Retorno completo por evento

3.4 Push

Escopos disponíveis

Retorno completo por evento

4. Comportamento do worker de webhooks