Saltar al contenido principal

Eventos de notificación (notification.*)

Ciclo de vida de los mensajes enviados al deudor por la regla de cobranza (correo, SMS, WhatsApp...). El data es siempre un objeto de referencia compacto — el recurso completo está en GET /api/v1/notifications/{notificationId}.

Valores de channel: email · sms · whatsapp · voice · manual.

notification.sent​

Se dispara cuando el mensaje es aceptado por el proveedor de envío.

{
  "event": "notification.sent",
  "timestamp": "2026-07-23T09:00:05.000Z",
  "organizationId": "0f7a3c1e-2b4d-4e6f-8a9b-1c2d3e4f5a6b",
  "data": {
    "notificationId": "6f8a0c2e-4b6d-4e1f-9a3c-5d7f9b1e3a5c",
    "channel": "email",
    "recipient": "financeiro@paoquente.com.br",
    "chargeId": "4a2b6c8d-1e3f-4a5b-9c7d-2e4f6a8b0c1d",
    "personId": "7c1e9f2a-3b4d-4c5e-8f6a-1b2c3d4e5f60"
  }
}

chargeId es null en notificaciones no vinculadas a un cobro específico.

En el entorno de prueba (sandbox), el envío real se simula (no sale ningún correo/SMS/WhatsApp) pero este evento se sigue disparando con el campo adicional "sandbox": true en data — así validas tu consumidor de webhook sin enviar nada al deudor.

notification.delivered​

Se dispara cuando el proveedor confirma la entrega al destinatario.

{
  "event": "notification.delivered",
  "timestamp": "2026-07-23T09:00:41.000Z",
  "organizationId": "0f7a3c1e-2b4d-4e6f-8a9b-1c2d3e4f5a6b",
  "data": {
    "notificationId": "6f8a0c2e-4b6d-4e1f-9a3c-5d7f9b1e3a5c",
    "channel": "email",
    "deliveredAt": "2026-07-23T09:00:40.000Z"
  }
}

notification.read​

Se dispara cuando el canal reporta lectura (no todos los canales la reportan).

{
  "event": "notification.read",
  "timestamp": "2026-07-23T10:12:03.000Z",
  "organizationId": "0f7a3c1e-2b4d-4e6f-8a9b-1c2d3e4f5a6b",
  "data": {
    "notificationId": "6f8a0c2e-4b6d-4e1f-9a3c-5d7f9b1e3a5c",
    "channel": "email",
    "readAt": "2026-07-23T10:12:01.000Z"
  }
}

notification.failed​

Se dispara en fallos de envío o de entrega (bounce). El campo extra identifica el origen:

Fallo en el envío (el proveedor rechazó/error en la llamada) — campo error:

{
  "event": "notification.failed",
  "timestamp": "2026-07-23T09:00:06.000Z",
  "organizationId": "0f7a3c1e-2b4d-4e6f-8a9b-1c2d3e4f5a6b",
  "data": {
    "notificationId": "6f8a0c2e-4b6d-4e1f-9a3c-5d7f9b1e3a5c",
    "channel": "whatsapp",
    "error": "Provider timeout after 10000ms"
  }
}

Bounce (entrega rechazada por el destino) — campo reason; si el canal es correo, la dirección se marca como inválida en el registro del cliente:

{
  "event": "notification.failed",
  "timestamp": "2026-07-23T09:03:18.000Z",
  "organizationId": "0f7a3c1e-2b4d-4e6f-8a9b-1c2d3e4f5a6b",
  "data": {
    "notificationId": "6f8a0c2e-4b6d-4e1f-9a3c-5d7f9b1e3a5c",
    "channel": "email",
    "reason": "Mailbox does not exist"
  }
}