Pular para o conteúdo principal

Eventos de notificação (notification.*)

Ciclo de vida das mensagens enviadas ao devedor pela régua (e-mail, SMS, WhatsApp...). O data é sempre um objeto de referência enxuto — o recurso completo está em GET /api/v1/notifications/{notificationId}.

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

notification.sent​

Dispara quando a mensagem é aceita pelo provedor de envio.

{
  "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 é null em notificações não vinculadas a uma cobrança específica.

No ambiente de teste (sandbox), o envio real é simulado (nenhum e-mail/SMS/WhatsApp sai) mas este evento continua sendo disparado com o campo adicional "sandbox": true em data — assim você valida o consumidor de webhook sem enviar nada ao devedor.

notification.delivered​

Dispara quando o provedor confirma a entrega ao destinatário.

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

Dispara quando o canal reporta leitura (nem todo canal reporta).

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

Dispara em falha de envio ou de entrega (bounce). O campo extra identifica a origem:

Falha no envio (o provedor recusou/erro na chamada) — 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 recusada pelo destino) — campo reason; se o canal for e-mail, o endereço é marcado como inválido no cadastro do 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"
  }
}