Eventos de Webhook

Con la API usted pregunta; con webhooks Notifique le avisa. Ideal para marcar pedidos entregados, medir aperturas o suprimir quienes se quejan, sin polling.

En resumen

Cada entrega es un POST application/json a su URL registrada.
Los eventos email.* son solo email; WhatsApp usa message.*, SMS usa sms.*.
instanceId está vacío (email no usa instance).
Habilite solo los eventos que necesite su integración.
Responda 2xx rápido; el procesamiento pesado va a su cola.

Configuración general: Webhooks. Seguridad (firma HMAC): Seguridad de Webhook.

Cómo se ve el POST

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

Campo	Descripción
`event`	Event name (e.g. `email.delivered`)
`workspaceId`	ID del Workspace
`instanceId`	Always empty for email
`timestamp`	ISO 8601, use para anti-replay
`data`	Send fields (`emailId`, `to`, `from`, `status`, etc.)

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

Qué debe devolver su servidor

Respuesta	Efecto
2xx en ~10s	Evento entregado; removido de la cola
4xx / 5xx / timeout	Reintento automático (5 min, 30 min, 2 h)

¿Procesamiento lento? Devuelva 200 de inmediato y procese en segundo plano. Más de ~10 s cuentan como tiempo de espera y el evento puede volver a enviarse.

Validate X-Notifique-Signature and a recent timestamp. Details: Webhook security.

Referencia de eventos

Use estos eventos al integrar e-commerce, ERP o automatización con email.

Envío y engagement

Evento	Cuándo se dispara	Qué hacer con él
`email.sent`	Email accepted and sent	Marcar como enviado
`email.delivered`	Provider confirmed inbox delivery	Confirmar entrega
`email.opened`	Recipient opened (first tracked open)	Engagement, lead caliente
`email.clicked`	Click on a tracked link in the email	Conversión, embudo
`email.failed`	Bounce or send error	Limpiar lista, alertar
`email.complained`	Marked as spam	Suprimir dirección
`email.cancelled`	Scheduled send cancelled before dispatch	Actualizar campaña

Payload por evento

Cuerpo POST completo. El sobre (event, ids, timestamp) coincide con el ejemplo anterior; abajo cambia lo de data.

email.sent

{
  "event": "email.sent",
  "workspaceId": "clxx123...",
  "instanceId": "",
  "timestamp": "2025-02-10T14:29:00.000Z",
  "data": {
    "emailId": "clxx456...",
    "to": "customer@example.com",
    "from": "noreply@yourdomain.com",
    "subject": "Order confirmation",
    "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": "customer@example.com",
    "from": "noreply@yourdomain.com",
    "status": "DELIVERED",
    "deliveredAt": "2025-02-10T14:30:05.000Z"
  }
}

email.opened

Se dispara en la primera apertura rastreada de este envío.

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

email.clicked

Se dispara en el primer clic en un enlace rastreado (o short link asignado).

{
  "event": "email.clicked",
  "workspaceId": "clxx123...",
  "instanceId": "",
  "timestamp": "2025-02-10T14:36:00.000Z",
  "data": {
    "emailId": "clxx456...",
    "to": "customer@example.com",
    "from": "noreply@yourdomain.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": "customer@example.com",
    "from": "noreply@yourdomain.com",
    "status": "FAILED",
    "failedAt": "2025-02-10T14:29:30.000Z",
    "errorMessage": "bounce_hard"
  }
}

email.complained

Buena práctica: agregue to a una lista de supresión al recibir este evento.

{
  "event": "email.complained",
  "workspaceId": "clxx123...",
  "instanceId": "",
  "timestamp": "2025-02-10T15:00:00.000Z",
  "data": {
    "emailId": "clxx456...",
    "to": "customer@example.com",
    "from": "noreply@yourdomain.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": "customer@example.com",
    "from": "noreply@yourdomain.com",
    "status": "CANCELLED"
  }
}

Próximos pasos

Inicio rápido: primer envío
Introducción: ciclo de estados
Alcances: permisos de la clave
Webhooks (general guide)

​En resumen

​Cómo se ve el POST

​Qué debe devolver su servidor

​Referencia de eventos

​Envío y engagement

​Payload por evento

​Próximos pasos

En resumen

Cómo se ve el POST

Qué debe devolver su servidor

Referencia de eventos

Envío y engagement

Payload por evento

Próximos pasos