Skip to main content
Com os webhooks de e-mail você é notificado em tempo real sobre o ciclo de vida dos seus envios: quando o e-mail foi aceito e enviado ao provedor, quando foi entregue, quando o destinatário abriu (open tracking), quando clicou em um link (click tracking), quando falhou (bounce) ou quando o destinatário marcou como spam (complaint).

​
Estrutura do corpo (payload)

O corpo da requisição segue sempre esta estrutura padrão, facilitando a tipagem no seu backend: 
{
  "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"
  }
}
Nos eventos de e-mail, o campo instanceId vem vazio, pois e-mail não usa instâncias (diferente do WhatsApp). O identificador do e-mail e os dados do evento ficam em data (emailId, to, from, status, sent_at, delivered_at, failed_at, error_message, etc.). Os campos de identificação (event, workspace_id, timestamp) são constantes.

​
Tabela de Eventos (Escopos)

Ao configurar um Webhook no painel, você escolhe quais eventos deseja ouvir. Para e-mail, ative apenas o que for útil para sua aplicação.

​
Eventos de ciclo de vida do e-mail

  • email.sent E-mail foi aceito e enviado ao provedor.
  • email.delivered E-mail foi entregue ao destinatário.
  • email.opened Destinatário abriu o e-mail pela primeira vez (open tracking).
  • email.clicked Destinatário clicou em um link do e-mail (click tracking).
  • email.failed E-mail falhou no envio ou bounce.
  • email.complained Reclamação de spam (complaint).
  • email.cancelled E-mail agendado foi cancelado.

​
Retorno de cada evento (E-mail)

Abaixo, o corpo completo (body) que a Notifique envia no POST para cada evento de e-mail. O campo data é o que varia; o restante da estrutura é sempre o mesmo. email.sent 
{
  "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"
  }
}
Campo opcional em data: sentAt. email.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",
    "deliveredAt": "2025-02-20T14:00:05.000Z"
  }
}
Campo opcional em data: deliveredAt. email.opened 
{
  "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"
  }
}
Campo opcional em data: openedAt. Disparado na primeira abertura do e-mail (open tracking do provedor). email.clicked 
{
  "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"
  }
}
Campo opcional em data: clickedAt. Disparado quando o destinatário clica em um link rastreado do e-mail (click tracking do provedor). email.failed 
{
  "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",
    "failedAt": "2025-02-20T14:00:00.000Z",
    "errorMessage": "Invalid address"
  }
}
Campos opcionais em data: failedAt, errorMessage. email.complained 
{
  "event": "email.complained",
  "workspaceId": "clxxworkspace123",
  "instanceId": "",
  "timestamp": "2025-02-20T14:00:00.000Z",
  "data": {
    "emailId": "clxxemail123",
    "to": "cliente@example.com",
    "from": "noreply@seudominio.com",
    "status": "COMPLAINED"
  }
}
Todos os campos em data são enviados (nenhum opcional).
Em email.complained, é boa prática adicionar o endereço to a uma lista de supressão e parar de enviar e-mails para esse destinatário, para evitar penalizações do provedor.
email.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"
  }
}
Disparado quando um e-mail agendado é cancelado via API ou painel.

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

Para garantir que o POST veio da Notifique e não de um terceiro, a Notifique envia headers de assinatura em todas as requisições de webhook.
HeaderDescrição
X-Notifique-SignatureHash HMAC-SHA256 do corpo da requisição, assinado com seu Segredo de Webhook. Formato: t=timestamp,v1=hash.
X-Notifique-TimestampMomento exato (Unix Timestamp em segundos) em que o evento foi gerado. Use para evitar Replay Attacks.
X-Workspace-IdID do workspace, para facilitar roteamento em sistemas multi-tenant.
X-Webhook-EventNome do evento (ex.: email.sent, email.delivered, email.opened, email.clicked, email.failed, email.complained, email.cancelled).
Content-Typeapplication/json.
Dica de segurança: Sempre verifique se o timestamp é recente (ex.: menos de 5 minutos) e recalcule o hash para validar a origem. O cálculo da assinatura é: HMAC-SHA256(secret, timestamp + ”.” + body), onde body é o corpo bruto do POST (string JSON).

​
Respostas esperadas

O seu servidor deve responder à requisição o mais rápido possível para evitar timeouts.
StatusSignificado
2xxSucesso. O evento é marcado como entregue e sai da fila da Notifique.
4xx / 5xx / timeoutFalha. A Notifique agenda retentativas automáticas (ex.: 5 min, 30 min, 2 h; até 4 tentativas).
Importante: Se o seu processamento for demorado (ex.: atualizar um CRM ou lista de supressão ao receber email.delivered ou email.complained), responda 200 OK imediatamente e processe a lógica em background (job assíncrono). Se você demorar mais de 10 segundos, a Notifique considerará timeout e reenviará o evento.