Eventos dos Webhooks

Na API você pergunta; no webhook a Notifique avisa. Ideal para marcar pedido como entregue, medir abertura ou suprimir quem reclamou spam, sem polling.

Em poucas palavras

Toda entrega é um POST application/json para a URL cadastrada.
Eventos email.* são só e-mail, WhatsApp usa message.*, SMS usa sms.*.
instanceId vem vazio (e-mail não usa instância).
Ative só os eventos que sua integração usa.
Responda 2xx rápido; processamento pesado vai para fila no seu lado.

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

Como vem o POST

{
  "event": "email.delivered",
  "workspaceId": "clxx123...",
  "instanceId": "",
  "timestamp": "2025-02-10T14:30:00.000Z",
  "data": {
    "emailId": "clxx456...",
    "to": "cliente@example.com",
    "from": "noreply@seudominio.com",
    "status": "DELIVERED",
    "deliveredAt": "2025-02-10T14:30:05.000Z"
  }
}

Campo	Descrição
`event`	Nome do evento (ex.: `email.delivered`)
`workspaceId`	ID do workspace
`instanceId`	Sempre vazio no e-mail
`timestamp`	ISO 8601, use para anti-replay
`data`	Campos do envio (`emailId`, `to`, `from`, `status`, etc.)

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

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. Acima de ~10 s 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 e-commerce, ERP ou automação com e-mail.

Envio e engajamento

Evento	Quando dispara	O que fazer com isso
`email.sent`	E-mail aceito e enviado	Marcar como enviado
`email.delivered`	Provedor confirmou entrega na caixa	Confirmar inbox
`email.opened`	Destinatário abriu (primeira abertura rastreada)	Engajamento, lead quente
`email.clicked`	Clique em link rastreado do e-mail	Conversão, funil
`email.failed`	Bounce ou erro de envio	Limpar lista, alertar
`email.complained`	Marcado como spam	Suprimir endereço
`email.cancelled`	Agendamento cancelado antes do envio	Atualizar campanha

Payload de cada evento

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

email.sent

{
  "event": "email.sent",
  "workspaceId": "clxx123...",
  "instanceId": "",
  "timestamp": "2025-02-10T14:29:00.000Z",
  "data": {
    "emailId": "clxx456...",
    "to": "cliente@example.com",
    "from": "noreply@seudominio.com",
    "subject": "Confirmação de pedido",
    "status": "SENT",
    "sentAt": "2025-02-10T14:29:00.000Z"
  }
}

email.delivered

{
  "event": "email.delivered",
  "workspaceId": "clxx123...",
  "instanceId": "",
  "timestamp": "2025-02-10T14:30:00.000Z",
  "data": {
    "emailId": "clxx456...",
    "to": "cliente@example.com",
    "from": "noreply@seudominio.com",
    "status": "DELIVERED",
    "deliveredAt": "2025-02-10T14:30:05.000Z"
  }
}

email.opened

Disparado na primeira abertura rastreada deste envio.

{
  "event": "email.opened",
  "workspaceId": "clxx123...",
  "instanceId": "",
  "timestamp": "2025-02-10T14:35:00.000Z",
  "data": {
    "emailId": "clxx456...",
    "to": "cliente@example.com",
    "from": "noreply@seudominio.com",
    "status": "OPENED",
    "openedAt": "2025-02-10T14:35:00.000Z"
  }
}

email.clicked

Disparado no primeiro clique em link rastreado deste envio (ou link curto atribuído).

{
  "event": "email.clicked",
  "workspaceId": "clxx123...",
  "instanceId": "",
  "timestamp": "2025-02-10T14:36:00.000Z",
  "data": {
    "emailId": "clxx456...",
    "to": "cliente@example.com",
    "from": "noreply@seudominio.com",
    "status": "CLICKED",
    "clickedAt": "2025-02-10T14:36:00.000Z"
  }
}

email.failed

{
  "event": "email.failed",
  "workspaceId": "clxx123...",
  "instanceId": "",
  "timestamp": "2025-02-10T14:29:30.000Z",
  "data": {
    "emailId": "clxx456...",
    "to": "cliente@example.com",
    "from": "noreply@seudominio.com",
    "status": "FAILED",
    "failedAt": "2025-02-10T14:29:30.000Z",
    "errorMessage": "bounce_hard"
  }
}

email.complained

Boa prática: incluir o to em lista de supressão ao receber este evento.

{
  "event": "email.complained",
  "workspaceId": "clxx123...",
  "instanceId": "",
  "timestamp": "2025-02-10T15:00:00.000Z",
  "data": {
    "emailId": "clxx456...",
    "to": "cliente@example.com",
    "from": "noreply@seudominio.com",
    "status": "COMPLAINED",
    "complainedAt": "2025-02-10T15:00:00.000Z"
  }
}

email.cancelled

{
  "event": "email.cancelled",
  "workspaceId": "clxx123...",
  "instanceId": "",
  "timestamp": "2025-02-10T12:00:00.000Z",
  "data": {
    "emailId": "clxx456...",
    "to": "cliente@example.com",
    "from": "noreply@seudominio.com",
    "status": "CANCELLED"
  }
}

Próximos passos

Quick Start: primeiro envio
Introdução: ciclo de status
Escopos: permissões da chave
Webhooks (guia geral)

​Em poucas palavras

​Como vem o POST

​O que seu servidor deve responder

​Referência por evento

​Envio e engajamento

​Payload de cada evento

​Próximos passos

Em poucas palavras

Como vem o POST

O que seu servidor deve responder

Referência por evento

Envio e engajamento

Payload de cada evento

Próximos passos