# Webhook Events

This page documents all event types sent via webhook by the FluxiQ NPC platform.

## Payload Format

All webhooks follow the same base format:

```json
{
  "event": "event_type",
  "timestamp": "2026-02-03T14:30:00Z",
  "data": {
    // Event-specific data
  }
}
```

| Field | Type | Description |
|-------|------|-------------|
| `event` | string | Event type (e.g., `boleto_paid`) |
| `timestamp` | string | Event date/time in ISO 8601 format (UTC) |
| `data` | object | Event-specific data |

## Boleto Events

### boleto_created

Sent when a new boleto is created in the system.

```json
{
  "event": "boleto_created",
  "timestamp": "2026-02-03T14:30:00Z",
  "data": {
    "nosso_numero": "00000000000000001",
    "codigo_barras": "23793.38128 60000.000003 00000.000406 1 84660000010000",
    "linha_digitavel": "23793381286000000000300000004061846600000100 00",
    "valor": 10000,
    "vencimento": "2026-03-15",
    "status": "draft",
    "pagador": {
      "nome": "Joao Silva",
      "documento": "12345678901",
      "tipo_documento": "cpf"
    },
    "beneficiario": {
      "nome": "Empresa LTDA",
      "documento": "12345678000190"
    },
    "created_at": "2026-02-03T14:30:00Z"
  }
}
```

**Event fields:**

| Field | Type | Description |
|-------|------|-------------|
| `nosso_numero` | string | Unique boleto identifier |
| `codigo_barras` | string | 44-digit barcode |
| `linha_digitavel` | string | 47-digit typeable line |
| `valor` | integer | Value in cents |
| `vencimento` | string | Due date (YYYY-MM-DD) |
| `status` | string | Boleto status (`draft`) |
| `pagador` | object | Payer data |
| `beneficiario` | object | Beneficiary data |
| `created_at` | string | Creation date/time |

### boleto_registered

Sent when the boleto is successfully registered with Nuclea (PCR).

```json
{
  "event": "boleto_registered",
  "timestamp": "2026-02-03T14:35:00Z",
  "data": {
    "nosso_numero": "00000000000000001",
    "codigo_barras": "23793.38128 60000.000003 00000.000406 1 84660000010000",
    "linha_digitavel": "23793381286000000000300000004061846600000100 00",
    "valor": 10000,
    "vencimento": "2026-03-15",
    "status": "registered",
    "pcr_protocol": "PCR2026020312345678",
    "registered_at": "2026-02-03T14:35:00Z",
    "pagador": {
      "nome": "Joao Silva",
      "documento": "12345678901",
      "tipo_documento": "cpf"
    },
    "beneficiario": {
      "nome": "Empresa LTDA",
      "documento": "12345678000190"
    }
  }
}
```

**Additional fields:**

| Field | Type | Description |
|-------|------|-------------|
| `status` | string | Updated status (`registered`) |
| `pcr_protocol` | string | Nuclea registration protocol |
| `registered_at` | string | Registration date/time |

### boleto_paid

Sent when a payment is confirmed for the boleto.

```json
{
  "event": "boleto_paid",
  "timestamp": "2026-02-04T09:15:00Z",
  "data": {
    "nosso_numero": "00000000000000001",
    "codigo_barras": "23793.38128 60000.000003 00000.000406 1 84660000010000",
    "valor_original": 10000,
    "valor_pago": 10000,
    "valor_desconto": 0,
    "valor_juros": 0,
    "valor_multa": 0,
    "status": "paid",
    "data_pagamento": "2026-02-04",
    "data_credito": "2026-02-05",
    "canal_pagamento": "internet_banking",
    "banco_pagador": "001",
    "agencia_pagador": "1234",
    "settlement_id": "stl_abc123def456",
    "paid_at": "2026-02-04T09:15:00Z"
  }
}
```

**Specific fields:**

| Field | Type | Description |
|-------|------|-------------|
| `valor_original` | integer | Original boleto value (cents) |
| `valor_pago` | integer | Amount actually paid (cents) |
| `valor_desconto` | integer | Discount applied (cents) |
| `valor_juros` | integer | Interest charged (cents) |
| `valor_multa` | integer | Penalty charged (cents) |
| `data_pagamento` | string | Payment date (YYYY-MM-DD) |
| `data_credito` | string | Expected credit date (YYYY-MM-DD) |
| `canal_pagamento` | string | Payment channel used |
| `banco_pagador` | string | Payer bank code (COMPE) |
| `agencia_pagador` | string | Payer branch |
| `settlement_id` | string | Settlement cycle ID |

**Payment channels:**

| Value | Description |
|-------|-------------|
| `internet_banking` | Internet Banking |
| `mobile_banking` | Bank app |
| `atm` | ATM |
| `branch` | Bank branch |
| `lottery` | Lottery outlet |
| `correspondent` | Banking correspondent |

### boleto_cancelled

Sent when a boleto is cancelled.

```json
{
  "event": "boleto_cancelled",
  "timestamp": "2026-02-03T16:00:00Z",
  "data": {
    "nosso_numero": "00000000000000001",
    "codigo_barras": "23793.38128 60000.000003 00000.000406 1 84660000010000",
    "valor": 10000,
    "vencimento": "2026-03-15",
    "status": "cancelled",
    "motivo_cancelamento": "solicitacao_cliente",
    "cancelled_at": "2026-02-03T16:00:00Z",
    "cancelled_by": "admin@empresa.com.br"
  }
}
```

**Specific fields:**

| Field | Type | Description |
|-------|------|-------------|
| `motivo_cancelamento` | string | Cancellation reason |
| `cancelled_at` | string | Cancellation date/time |
| `cancelled_by` | string | User who requested cancellation |

**Cancellation reasons:**

| Value | Description |
|-------|-------------|
| `solicitacao_cliente` | Customer request |
| `erro_emissao` | Issuance error |
| `duplicidade` | Duplicate boleto |
| `acordo` | Negotiation/agreement |
| `outros` | Other reasons |

## Settlement Events

### settlement_completed

Sent when a settlement cycle is successfully processed.

```json
{
  "event": "settlement_completed",
  "timestamp": "2026-02-04T08:45:00Z",
  "data": {
    "settlement_id": "stl_abc123def456",
    "cycle_date": "2026-02-04",
    "cycle_type": "morning",
    "total_boletos": 47,
    "total_valor": 1523450,
    "arquivo_acmp615": "ACMP615.20260204.083000",
    "status": "completed",
    "started_at": "2026-02-04T08:35:00Z",
    "completed_at": "2026-02-04T08:45:00Z",
    "summary": {
      "pagos": 45,
      "valor_pagos": 1485000,
      "rejeitados": 2,
      "valor_rejeitados": 38450
    }
  }
}
```

**Event fields:**

| Field | Type | Description |
|-------|------|-------------|
| `settlement_id` | string | Unique settlement cycle ID |
| `cycle_date` | string | Cycle date (YYYY-MM-DD) |
| `cycle_type` | string | Cycle type (`morning` or `afternoon`) |
| `total_boletos` | integer | Total boletos processed |
| `total_valor` | integer | Total value processed (cents) |
| `arquivo_acmp615` | string | ACMP615 file name processed |
| `summary` | object | Summary by status |

**Cycle types:**

| Value | Time | Description |
|-------|------|-------------|
| `morning` | 08:30 | Morning cycle |
| `afternoon` | 16:30 | Afternoon cycle |

### payment_received

Sent for each individual payment received during settlement processing. This event complements `boleto_paid` and provides additional information from the ACMP615 file.

```json
{
  "event": "payment_received",
  "timestamp": "2026-02-04T08:40:00Z",
  "data": {
    "settlement_id": "stl_abc123def456",
    "nosso_numero": "00000000000000001",
    "codigo_barras": "23793.38128 60000.000003 00000.000406 1 84660000010000",
    "valor_pago": 10000,
    "data_pagamento": "2026-02-04",
    "data_credito": "2026-02-05",
    "banco_recebedor": "237",
    "agencia_recebedora": "1234",
    "tipo_liquidacao": "normal",
    "sequencial_arquivo": 15,
    "acmp615_record": {
      "tipo_registro": "20",
      "codigo_movimento": "06"
    }
  }
}
```

**Specific fields:**

| Field | Type | Description |
|-------|------|-------------|
| `settlement_id` | string | Settlement cycle ID |
| `banco_recebedor` | string | Bank that received the payment |
| `agencia_recebedora` | string | Branch that received |
| `tipo_liquidacao` | string | Settlement type |
| `sequencial_arquivo` | integer | Position in ACMP615 file |
| `acmp615_record` | object | Raw ACMP615 record data |

**Settlement types:**

| Value | Description |
|-------|-------------|
| `normal` | Standard D+1 settlement |
| `express` | Express D+0 settlement |
| `dda` | Via Direct Debit Authorization |

## Event Summary

| Event | Trigger | Key Fields |
|-------|---------|------------|
| `boleto_created` | Boleto created in system | `nosso_numero`, `valor`, `status` |
| `boleto_registered` | Registration confirmed at Nuclea | `nosso_numero`, `pcr_protocol`, `status` |
| `boleto_paid` | Payment confirmed | `nosso_numero`, `valor_pago`, `settlement_id` |
| `boleto_cancelled` | Boleto cancelled | `nosso_numero`, `motivo_cancelamento` |
| `settlement_completed` | Settlement cycle finished | `settlement_id`, `total_boletos`, `summary` |
| `payment_received` | Individual payment processed | `settlement_id`, `nosso_numero`, `valor_pago` |

## Testing Events

### Sandbox Environment

In sandbox, you can trigger test events to validate your integration:

```bash
# Trigger boleto paid event
curl -X POST "https://sandbox.monetarie_npc.com.br/api/v1/central/webhooks/test" \
  -H "X-API-Key: pk_test_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "boleto_paid",
    "nosso_numero": "00000000000000001"
  }'
```

**Event types available for testing:**

| event_type | Description |
|------------|-------------|
| `boleto_created` | Simulates boleto creation |
| `boleto_registered` | Simulates Nuclea registration |
| `boleto_paid` | Simulates payment |
| `boleto_cancelled` | Simulates cancellation |
| `settlement_completed` | Simulates settlement cycle |
| `payment_received` | Simulates individual payment |

### Using webhook.site

For development and debugging, we recommend using [webhook.site](https://webhook.site):

1. Go to [webhook.site](https://webhook.site)
2. Copy the unique URL generated
3. Configure as `webhook_url` in the portal (sandbox)
4. Execute actions or trigger test events
5. View payloads in real-time

::: tip Inspecting Payloads
webhook.site allows you to see all headers, request body, and metadata. This is useful for debugging signature or format issues.
:::

### Local Simulator

For local development, you can use [ngrok](https://ngrok.com) to expose your machine:

```bash
# Start ngrok
ngrok http 3000

# Output:
# Forwarding: https://abc123.ngrok.io -> http://localhost:3000

# Configure URL in portal
curl -X PUT "https://sandbox.monetarie_npc.com.br/api/v1/central/config/central" \
  -H "X-API-Key: pk_test_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "https://abc123.ngrok.io/webhooks/monetarie_npc"
  }'
```

## Next Steps

- [Implementation](/en/webhooks/handling) - Complete implementation guide
- [Security](/en/webhooks/#security) - Signature validation
- [Settlement Flow](/en/guides/settlement-flow) - Understand the settlement process