Skip to main content

Notification events (notification.*)

Lifecycle of the messages the collection rule sends to the debtor (email, SMS, WhatsApp...). data is always a lean reference object — the full resource lives at GET /api/v1/notifications/{notificationId}.

channel values: email · sms · whatsapp · voice · manual.

notification.sent​

Fires when the message is accepted by the sending provider.

{
  "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 is null in notifications not tied to a specific charge.

In the test environment (sandbox), the real send is simulated (no email/SMS/WhatsApp goes out) but this event is still dispatched with an extra "sandbox": true field in data — so you can validate your webhook consumer without sending anything to the debtor.

notification.delivered​

Fires when the provider confirms delivery to the recipient.

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

Fires when the channel reports a read (not every channel does).

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

Fires on a send failure or a delivery failure (bounce). The extra field identifies the origin:

Send failure (the provider refused/errored on the call) — error field:

{
  "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 (delivery refused by the destination) — reason field; when the channel is email, the address is flagged as invalid on the customer record:

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