Eventos de Webhook

Esta pagina documenta todos os tipos de eventos enviados via webhook pela plataforma FluxiQ NPC.

Formato do Payload

Todos os webhooks seguem o mesmo formato base:

{
  "event": "tipo_do_evento",
  "timestamp": "2026-02-03T14:30:00Z",
  "data": {
    // Dados especificos do evento
  }
}

Campo	Tipo	Descricao
event	string	Tipo do evento (ex: boleto_paid)
timestamp	string	Data/hora do evento em formato ISO 8601 (UTC)
data	object	Dados especificos do evento

Eventos de Boleto

boleto_created

Enviado quando um novo boleto e criado no sistema.

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

Campos do evento:

Campo	Tipo	Descricao
nosso_numero	string	Identificador unico do boleto
codigo_barras	string	Codigo de barras de 44 digitos
linha_digitavel	string	Linha digitavel de 47 digitos
valor	integer	Valor em centavos
vencimento	string	Data de vencimento (YYYY-MM-DD)
status	string	Status do boleto (draft)
pagador	object	Dados do pagador
beneficiario	object	Dados do beneficiario
created_at	string	Data/hora de criacao

boleto_registered

Enviado quando o boleto e registrado com sucesso na Nuclea (PCR).

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

Campos adicionais:

Campo	Tipo	Descricao
status	string	Status atualizado (registered)
pcr_protocol	string	Protocolo de registro na Nuclea
registered_at	string	Data/hora do registro

boleto_paid

Enviado quando um pagamento e confirmado para o boleto.

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

Campos especificos:

Campo	Tipo	Descricao
valor_original	integer	Valor original do boleto (centavos)
valor_pago	integer	Valor efetivamente pago (centavos)
valor_desconto	integer	Desconto aplicado (centavos)
valor_juros	integer	Juros cobrados (centavos)
valor_multa	integer	Multa cobrada (centavos)
data_pagamento	string	Data do pagamento (YYYY-MM-DD)
data_credito	string	Data prevista para credito (YYYY-MM-DD)
canal_pagamento	string	Canal utilizado para pagamento
banco_pagador	string	Codigo do banco pagador (COMPE)
agencia_pagador	string	Agencia do pagador
settlement_id	string	ID do ciclo de liquidacao

Canais de pagamento:

Valor	Descricao
internet_banking	Internet Banking
mobile_banking	App do banco
atm	Caixa eletronico
branch	Agencia bancaria
lottery	Casa loterica
correspondent	Correspondente bancario

boleto_cancelled

Enviado quando um boleto e cancelado.

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

Campos especificos:

Campo	Tipo	Descricao
motivo_cancelamento	string	Motivo do cancelamento
cancelled_at	string	Data/hora do cancelamento
cancelled_by	string	Usuario que solicitou o cancelamento

Motivos de cancelamento:

Valor	Descricao
solicitacao_cliente	Solicitado pelo cliente
erro_emissao	Erro na emissao
duplicidade	Boleto duplicado
acordo	Negociacao/acordo
outros	Outros motivos

Eventos de Liquidacao

settlement_completed

Enviado quando um ciclo de liquidacao e processado com sucesso.

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

Campos do evento:

Campo	Tipo	Descricao
settlement_id	string	ID unico do ciclo de liquidacao
cycle_date	string	Data do ciclo (YYYY-MM-DD)
cycle_type	string	Tipo do ciclo (morning ou afternoon)
total_boletos	integer	Total de boletos processados
total_valor	integer	Valor total processado (centavos)
arquivo_acmp615	string	Nome do arquivo ACMP615 processado
summary	object	Resumo por status

Tipos de ciclo:

Valor	Horario	Descricao
morning	08:30	Ciclo da manha
afternoon	16:30	Ciclo da tarde

payment_received

Enviado para cada pagamento individual recebido durante o processamento de liquidacao. Este evento e complementar ao boleto_paid e fornece informacoes adicionais do arquivo ACMP615.

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

Campos especificos:

Campo	Tipo	Descricao
settlement_id	string	ID do ciclo de liquidacao
banco_recebedor	string	Banco que recebeu o pagamento
agencia_recebedora	string	Agencia que recebeu
tipo_liquidacao	string	Tipo de liquidacao
sequencial_arquivo	integer	Posicao no arquivo ACMP615
acmp615_record	object	Dados brutos do registro ACMP615

Tipos de liquidacao:

Valor	Descricao
normal	Liquidacao padrao D+1
express	Liquidacao expressa D+0
dda	Via Debito Direto Autorizado

Resumo de Eventos

Evento	Trigger	Campos Chave
boleto_created	Boleto criado no sistema	nosso_numero, valor, status
boleto_registered	Registro confirmado na Nuclea	nosso_numero, pcr_protocol, status
boleto_paid	Pagamento confirmado	nosso_numero, valor_pago, settlement_id
boleto_cancelled	Boleto cancelado	nosso_numero, motivo_cancelamento
settlement_completed	Ciclo de liquidacao finalizado	settlement_id, total_boletos, summary
payment_received	Pagamento individual processado	settlement_id, nosso_numero, valor_pago

Testando Eventos

Ambiente Sandbox

No sandbox, voce pode disparar eventos de teste para validar sua integracao:

# Disparar evento de boleto pago
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"
  }'

Tipos de eventos disponiveis para teste:

event_type	Descricao
boleto_created	Simula criacao de boleto
boleto_registered	Simula registro na Nuclea
boleto_paid	Simula pagamento
boleto_cancelled	Simula cancelamento
settlement_completed	Simula ciclo de liquidacao
payment_received	Simula pagamento individual

Usando webhook.site

Para desenvolvimento e debug, recomendamos usar webhook.site:

1. Acesse webhook.site
2. Copie a URL unica gerada
3. Configure como webhook_url no portal (sandbox)
4. Execute acoes ou dispare eventos de teste
5. Visualize os payloads em tempo real

Inspecionando Payloads

O webhook.site permite ver todos os headers, corpo da requisicao e metadata. Isso e util para depurar problemas de assinatura ou formato.

Simulador Local

Para desenvolvimento local, voce pode usar o ngrok para expor sua maquina:

# Iniciar ngrok
ngrok http 3000

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

# Configurar URL no 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"
  }'

Proximos Passos

• Implementacao - Guia completo de implementacao
• Seguranca - Validacao de assinatura
• Fluxo de Liquidacao - Entenda o processo de liquidacao