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.pixconnect.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:

Go to webhook.site
Copy the unique URL generated
Configure as webhook_url in the portal (sandbox)
Execute actions or trigger test events
View payloads in real-time

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 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.pixconnect.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/pixconnect"
  }'

Next Steps

Implementation - Complete implementation guide
Security - Signature validation
Settlement Flow - Understand the settlement process

Webhook Events ​

Payload Format ​

Boleto Events ​

boleto_created ​

boleto_registered ​

boleto_paid ​

boleto_cancelled ​

Settlement Events ​

settlement_completed ​

payment_received ​

Event Summary ​

Testing Events ​

Sandbox Environment ​

Using webhook.site ​

Local Simulator ​

Next Steps ​

Webhook Events

Payload Format

Boleto Events

boleto_created

boleto_registered

boleto_paid

boleto_cancelled

Settlement Events

settlement_completed

payment_received

Event Summary

Testing Events

Sandbox Environment

Using webhook.site

Local Simulator

Next Steps