Endpoint para Recebimento de Webhooks

Seu endpoint deve ser uma URL HTTPS com um certificado SSL válido, capaz de receber requisições HTTP POST contendo um payload em JSON e headers customizados.

É considerado sucesso qualquer resposta com status code entre 200 e 299.

Se a requisição não receber resposta em até 10 segundos, será considerada uma falha, e a requisição será reenviada conforme a política de tentativas (Retry Policy).

É possível registrar:

Uma única URL para receber todos os eventos disponíveis, ou

URLs específicas para cada tópico/evento.

Após o registro do endpoint, a Neofin enviará um POST sempre que um evento ocorrer.

A Neofin verifica o certificado SSL ao entregar os webhooks. Certifique-se de que seu servidor está configurado corretamente para HTTPS com um certificado válido.

Política de Reenvio (Retry Policy)

A Neofin tentará enviar a notificação até 3 vezes, seguindo as seguintes regras:

Primeira tentativa: imediatamente após o evento atingir o estado necessário.

Segunda tentativa: se a primeira falhar, será feita 5 minutos depois.

Terceira e última tentativa: se a segunda também falhar, será feita 15 minutos depois da segunda tentativa.

Após esgotar as três tentativas, a Neofin deixa de reenviar aquele evento automaticamente.

Registro de Webhooks

API

Método: POST

{
  "URL": "https://api.sandbox.neofin.services/webhook",
  "Headers": {
    "api-key": "1A2B3C4D5E1A2B3C4D5E",
    "secret-key": "Aa1Bb2Aa1Bb2Aa1Bb2Aa1Bb2Aa1Bb2Aa1Bb2"
  },
  "Payload": {
    "topic": "payments/created",
    "destination": "https://url-do-webhook"
  }
}

Eventos disponíveis para registro no `topic`

payments/created

payments/registered

payments/overdue

payments/paid

payments/cancelled

Como os eventos são disparados

Cada webhook representa uma parcela de pagamento identificada pelo campo id do payload.

Campo no payload	Significado
`id`	Identificador único da parcela que disparou o evento
`parent_id`	Identificador da cobrança à qual a parcela pertence

Diferença entre `payments/created` e `payments/registered`

Ambos podem ter payment_status: "pending", mas o tópico muda conforme o estágio da parcela:

Tópico	Quando é enviado
`payments/created`	Parcela em criação ou quando houve alteração em: `payment_amount`, `due_date`, `fees`, `fine`, `discount_before_payment`, `discount_before_payment_due_date`
`payments/registered`	Parcela em aberto com boleto/PIX já disponíveis, sem alteração nos campos acima

`payment_status` retornados por tópico

O campo payment_status no payload indica o estado da parcela. O tópico (X-Neofin-Topic) indica qual URL/evento foi acionado.

`payments/created`

`payment_status`	Descrição
`pending`	Em aberto (criação ou alteração de valores)

`payments/registered`

`payment_status`	Descrição
`pending`	Em aberto (registrado com meios de pagamento)

`payments/overdue`

`payment_status`	Descrição
`overdue`	Vencido
`processing_protest`	Protesto (em andamento)
`protested`	Protestado
`derrogatory`	Negativado
`processing_derrogatory`	Negativação (em andamento)
`derrogatory_cancelled`	Negativação cancelada
`protest_cancelled`	Protesto baixado

`payments/paid`

`payment_status`	Descrição
`paid`	Recebido
`paid_after_protested`	Protestado recebido
`paid_after_derrogatory`	Negativação paga

Regras do evento `payments/paid`

O pagamento de uma parcela pode gerar mais de um webhook payments/paid ao longo do processamento. Para baixar o pagamento no seu sistema, considere as regras abaixo:

Campo	Regra
`payment_status`	Será `paid`, `paid_after_protested` ou `paid_after_derrogatory`
`payment_substatus`	Quando o valor estiver creditado, será `"credited"`
`paid_amount`	Preenchido corretamente (valor efetivo em centavos) quando `payment_substatus` for `"credited"`
`paid_at`	Data/hora do pagamento (timestamp em segundos)
`paid_method`	Meio efetivo utilizado: `pix` ou `boleto`

Recomendação: utilize o evento payments/paid com payment_substatus: "credited" como confirmação definitiva do valor pago. Nesse evento, o campo paid_amount reflete o valor creditado e pode ser usado para conciliação.

Exemplo — pagamento creditado:

{
  "payment_status": "paid",
  "payment_substatus": "credited",
  "paid_amount": 15000,
  "paid_at": 1681845201,
  "paid_method": "pix"
}

`payments/cancelled`

`payment_status`	Descrição
`cancelled`	Cancelado

Nota: parcelas com erro de processamento não disparam webhooks.

Renegociação e Acordos

Contexto

Uma renegociação ou acordo seleciona parcelas de um mesmo cliente (não necessariamente da mesma cobrança) e gera uma nova cobrança com novas parcelas.

Quando o webhook é disparado pelas novas parcelas da cobrança gerada, o payload inclui campos adicionais que identificam a origem renegociada.

Campos de renegociação no payload

Presentes em todos os tópicos (created, registered, overdue, paid, cancelled) quando a cobrança associada (parent_id) foi originada por renegociação ou acordo.

Campo	Tipo	Obrigatório	Descrição
`is_renegotiation`	`boolean`	Condicional	`true` quando a cobrança foi gerada por renegociação ou acordo
`renegotiation_type`	`string`	Condicional	Tipo da renegociação. Presente quando disponível
`renegotiation_payments`	`string[]`	Condicional	Lista de IDs das parcelas originais selecionadas para compor o acordo/renegociação

Regras de inclusão

Cobrança normal: os três campos não aparecem no payload.

is_renegotiation: incluído quando a cobrança foi gerada por renegociação ou acordo.

renegotiation_type: incluído somente quando informado. Omitido quando ausente.

renegotiation_payments: incluído somente quando informado. Omitido quando ausente ou lista vazia.

Valores de `renegotiation_type`

Valor	Origem
`AGREEMENT`	Acordo criado via portal externo
(ausente)	Renegociação via portal interno (até padronização futura com `RENEGOTIATION`)
`RENEGOTIATION`	(previsto) Renegociação via portal interno

O que são os IDs em `renegotiation_payments`?

Apesar do nome, renegotiation_payments contém identificadores de parcelas, não identificadores de pagamentos avulsos.

São as parcelas originais (dívidas anteriores) que foram selecionadas no acordo/renegociação. Essas parcelas:

Pertencem a cobranças anteriores (podem ser cobranças diferentes).

São do mesmo cliente da nova cobrança.

Não possuem is_renegotiation: true no payload quando geram eventos próprios (são as dívidas anteriores, não as novas parcelas).

Modelo de relacionamento

Parcelas originais (várias cobranças anteriores)
        │
        │  selecionadas no acordo/renegociação
        ▼
Nova cobrança (is_renegotiation = true)
  ├── renegotiation_type: "AGREEMENT" (quando acordo)
  ├── renegotiation_payments: ["id-parcela-1", "id-parcela-2", ...]
  └── novas parcelas
        │
        └── disparam webhooks com os campos acima no payload

Como usar os campos no integrador

Identificar a parcela do evento

Campo	Uso
`id`	Parcela nova (a parcela deste evento)
`parent_id`	Cobrança nova gerada pela renegociação/acordo
`payment_number`	Número da parcela nova (ex.: `42128424778890-1`)
`installment`	Ordem da parcela nova (ex.: `1/4`)

Identificar as parcelas originais renegociadas

Use a lista renegotiation_payments:

"renegotiation_payments": [
  "a3648694-5313-4f45-a72e-09ea22961f37",
  "88bcc91e-c657-4246-bad5-36907b234af8"
]

Cada string é o id de uma parcela original. Você pode correlacionar esses IDs com registros previamente recebidos via webhook ou consultá-los pela API Neofin.

Exemplo de payload com renegociação (`payments/created`)

{
  "id": "e54113a4-c595-4019-93c5-c0e4b96465bd",
  "parent_id": "0cda49ad-7b3e-4944-97b9-d2f9aca8d576",
  "payment_number": "42128424778890-3",
  "installment": "3/4",
  "payment_status": "pending",
  "payment_amount": 3779,
  "is_renegotiation": true,
  "renegotiation_type": "AGREEMENT",
  "renegotiation_payments": [
    "a3648694-5313-4f45-a72e-09ea22961f37",
    "88bcc91e-c657-4246-bad5-36907b234af8",
    "feb89ca4-85af-4fca-aad4-01e673ae16a9"
  ]
}

Exemplo de renegociação via portal interno (sem tipo)

{
  "id": "uuid-da-nova-parcela",
  "parent_id": "uuid-da-nova-cobranca",
  "is_renegotiation": true,
  "renegotiation_payments": [
    "uuid-parcela-original-1",
    "uuid-parcela-original-2"
  ]
}

Neste caso, renegotiation_type não está presente no payload. A ausência do tipo, com is_renegotiation = true, indica origem via portal interno de renegociação.

Webhooks das parcelas originais

As parcelas originais também podem gerar webhooks quando atualizadas (ex.: mudança de status). Nesses eventos:

parent_id aponta para a cobrança original de cada parcela.

Os campos is_renegotiation, renegotiation_type e renegotiation_payments não aparecem.

Referência completa de campos do payload

Campos base (todos os tópicos)

Campo	Tipo	Descrição
`id`	`string` (UUID)	Identificador da parcela
`parent_id`	`string` (UUID)	Identificador da cobrança
`customer_name`	`string`	Nome do cliente
`customer_document`	`string`	Documento do cliente (CPF/CNPJ)
`customer_mail`	`string`	E-mail do cliente
`customer_phone`	`string`	Telefone do cliente
`address_street`	`string`	Logradouro
`address_number`	`string`	Número
`address_complement`	`string`	Complemento
`address_neighborhood`	`string`	Bairro
`address_zip_code`	`string`	CEP
`address_city`	`string`	Cidade
`address_state`	`string`	Estado (UF)
`billing_amount`	`string`	Valor total da cobrança em centavos
`payment_number`	`string`	Número da parcela (ex.: `42128424778890-1`)
`payment_method`	`string`	Meio de pagamento (ver valores possíveis)
`payment_status`	`string`	Status da parcela (ver valores possíveis)
`payment_substatus`	`string`	Substatus do pagamento (ex.: `credited` quando creditado)
`payment_amount`	`number`	Valor da parcela em centavos
`description`	`string`	Descrição da parcela ou cobrança
`installment`	`string`	Ordem da parcela na cobrança (ex.: `1/4`)
`fine`	`number`	Multa (%)
`fees`	`number`	Juros (%)
`discount_before_payment`	`string`	Desconto para pagamento antecipado (valor em reais, ex.: `"0.0"`)
`discount_before_payment_due_date`	`integer`	Timestamp (segundos) limite para desconto; `0` se ausente
`due_date`	`integer`	Timestamp (segundos) do vencimento
`issued_at`	`integer`	Timestamp (segundos) de emissão da parcela
`integration_identifier`	`string`	Identificador de integração ERP
`os_code`	`string`	Código OS
`os_identifier`	`string`	Identificador OS
`nf_url`	`string`	URL da nota fiscal
`nfe_number`	`string`	Número da NFe
`danfe`	`string` ou `object`	DANFE (quando disponível)
`hash`	`string`	Payload PIX copia-e-cola (vazio se não aplicável)
`barcode_b64`	`string`	Código de barras do boleto em Base64 (vazio se não aplicável)
`code`	`string`	Linha digitável do boleto (vazio se não aplicável)
`boleto_url`	`string`	URL do PDF do boleto (vazio se não aplicável)
`paid_amount`	`integer`	Valor pago em centavos (`0` quando não pago ou ainda não creditado)
`paid_at`	`integer`	Timestamp (segundos) do pagamento (`0` quando não pago)
`payment_captured_at`	`integer`	Timestamp (segundos) da captura do pagamento (`0` quando não aplicável)
`paid_method`	`string`	Meio efetivo do pagamento: `pix` ou `boleto` (vazio se não pago)

Campos condicionais

Campo	Condição
`recipient_bank_internal_number`	Presente em alguns pagamentos bancários; omitido no evento `payments/created`
`is_renegotiation`	Presente quando a cobrança foi originada por renegociação ou acordo
`renegotiation_type`	Presente quando o tipo de renegociação está informado
`renegotiation_payments`	Presente quando há lista de parcelas originais informada

Exemplos de Payload/JSON

payments/created

{
  "id": "d2b836f9-659f-4c2f-96c0-9cb2b57919c9",
  "parent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "customer_name": "Customer Name LTDA",
  "customer_document": "11112222000199",
  "customer_mail": "customer@email.com",
  "customer_phone": "+5511977773333",
  "address_street": "Rua Teste",
  "address_number": "123",
  "address_complement": "CJ 1",
  "address_neighborhood": "Centro",
  "address_zip_code": "01005000",
  "address_city": "São Paulo",
  "address_state": "SP",
  "billing_amount": "15000",
  "payment_number": "11111999999999-1",
  "payment_method": "bolepix",
  "payment_status": "pending",
  "payment_substatus": "",
  "payment_amount": 15000,
  "description": "Cobrança 1111100000 - parcela 001/001",
  "installment": "1/1",
  "fine": 0.0,
  "fees": 0.0,
  "discount_before_payment": "0.0",
  "discount_before_payment_due_date": 1681757667,
  "due_date": 1681959600,
  "issued_at": 1681781894,
  "integration_identifier": "1234",
  "os_code": "8888888888",
  "os_identifier": "5678",
  "nf_url": "https://nf.co/123098",
  "nfe_number": "",
  "danfe": "",
  "hash": "",
  "barcode_b64": "",
  "code": "",
  "boleto_url": "",
  "paid_amount": 0,
  "paid_at": 0,
  "payment_captured_at": 0,
  "paid_method": "",
  "is_renegotiation": true,
  "renegotiation_type": "AGREEMENT",
  "renegotiation_payments": [
    "a3648694-5313-4f45-a72e-09ea22961f37",
    "88bcc91e-c657-4246-bad5-36907b234af8"
  ]
}

Campos de renegociação aparecem apenas quando aplicável. Cobranças normais não incluem is_renegotiation, renegotiation_type nem renegotiation_payments.

payments/registered

{
  "id": "d2b836f9-659f-4c2f-96c0-9cb2b57919c9",
  "parent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "customer_name": "Customer Name LTDA",
  "customer_document": "11112222000199",
  "customer_mail": "customer@email.com",
  "customer_phone": "+5511977773333",
  "address_street": "Rua Teste",
  "address_number": "123",
  "address_complement": "CJ 1",
  "address_neighborhood": "Centro",
  "address_zip_code": "01005000",
  "address_city": "São Paulo",
  "address_state": "SP",
  "billing_amount": "15000",
  "payment_number": "11111999999999-1",
  "payment_method": "bolepix",
  "payment_status": "pending",
  "payment_substatus": "",
  "payment_amount": 15000,
  "description": "Cobrança 1111100000 - parcela 001/001",
  "installment": "1/1",
  "fine": 0.0,
  "fees": 0.0,
  "discount_before_payment": "0.0",
  "discount_before_payment_due_date": 1681757667,
  "due_date": 1681959600,
  "issued_at": 1681781894,
  "integration_identifier": "1234",
  "os_code": "8888888888",
  "os_identifier": "5678",
  "nf_url": "https://nf.co/123098",
  "nfe_number": "",
  "danfe": "",
  "barcode_b64": "iVBORw0KGgo...",
  "boleto_url": "https://boletos.fitbank.com.br/pdf/2023-04-18/4044kt2s.pdf",
  "code": "45090.13781 00000.127805 00255.550032 1 94790000001295",
  "hash": "00030101021226780025br.gov.bcb.pix2556qrcode.fitbank.com.br/QR/cobv/...",
  "paid_amount": 0,
  "paid_at": 0,
  "payment_captured_at": 0,
  "paid_method": "",
  "recipient_bank_internal_number": "0020005600574072"
}

payments/overdue

{
  "id": "d2b836f9-659f-4c2f-96c0-9cb2b57919c9",
  "parent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "customer_name": "Customer Name LTDA",
  "customer_document": "11112222000199",
  "customer_mail": "customer@email.com",
  "customer_phone": "+5511977773333",
  "address_street": "Rua Teste",
  "address_number": "123",
  "address_complement": "CJ 1",
  "address_neighborhood": "Centro",
  "address_zip_code": "01005000",
  "address_city": "São Paulo",
  "address_state": "SP",
  "billing_amount": "15000",
  "payment_number": "11111999999999-1",
  "payment_method": "bolepix",
  "payment_status": "overdue",
  "payment_substatus": "",
  "payment_amount": 15000,
  "description": "Cobrança 1111100000 - parcela 001/001",
  "installment": "1/1",
  "fine": 0.0,
  "fees": 0.0,
  "discount_before_payment": "0.0",
  "discount_before_payment_due_date": 1681757667,
  "due_date": 1681959600,
  "issued_at": 1681781894,
  "integration_identifier": "1234",
  "os_code": "8888888888",
  "os_identifier": "5678",
  "nf_url": "https://nf.co/123098",
  "nfe_number": "",
  "danfe": "",
  "barcode_b64": "iVBORw0KGgo...",
  "boleto_url": "https://boletos.fitbank.com.br/pdf/2023-04-18/4044kt2s.pdf",
  "code": "45090.13781 00000.127805 00255.550032 1 94790000001295",
  "hash": "00030101021226780025br.gov.bcb.pix2556qrcode.fitbank.com.br/QR/cobv/...",
  "paid_amount": 0,
  "paid_at": 0,
  "payment_captured_at": 0,
  "paid_method": ""
}

payments/paid

{
  "id": "d2b836f9-659f-4c2f-96c0-9cb2b57919c9",
  "parent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "customer_name": "Customer Name LTDA",
  "customer_document": "11112222000199",
  "customer_mail": "customer@email.com",
  "customer_phone": "+5511977773333",
  "address_street": "Rua Teste",
  "address_number": "123",
  "address_complement": "CJ 1",
  "address_neighborhood": "Centro",
  "address_zip_code": "01005000",
  "address_city": "São Paulo",
  "address_state": "SP",
  "billing_amount": "15000",
  "payment_number": "11111999999999-1",
  "payment_method": "bolepix",
  "payment_status": "paid",
  "payment_substatus": "credited",
  "payment_amount": 15000,
  "description": "Cobrança 1111100000 - parcela 001/001",
  "installment": "1/1",
  "fine": 0.0,
  "fees": 0.0,
  "discount_before_payment": "0.0",
  "discount_before_payment_due_date": 1681757667,
  "due_date": 1681959600,
  "issued_at": 1681781894,
  "integration_identifier": "1234",
  "os_code": "8888888888",
  "os_identifier": "5678",
  "nf_url": "https://nf.co/123098",
  "nfe_number": "",
  "danfe": "",
  "barcode_b64": "iVBORw0KGgo...",
  "boleto_url": "https://boletos.fitbank.com.br/pdf/2023-04-18/4044kt2s.pdf",
  "code": "45090.13781 00000.127805 00255.550032 1 94790000001295",
  "hash": "00030101021226780025br.gov.bcb.pix2556qrcode.fitbank.com.br/QR/cobv/...",
  "paid_amount": 15000,
  "paid_at": 1681845201,
  "payment_captured_at": 1681845201,
  "paid_method": "pix"
}

Neste exemplo, payment_status: "paid" com payment_substatus: "credited" indica pagamento creditado. O campo paid_amount contém o valor efetivamente pago em centavos.

payments/cancelled

{
  "id": "d2b836f9-659f-4c2f-96c0-9cb2b57919c9",
  "parent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "customer_name": "Customer Name LTDA",
  "customer_document": "11112222000199",
  "customer_mail": "customer@email.com",
  "customer_phone": "+5511977773333",
  "address_street": "Rua Teste",
  "address_number": "123",
  "address_complement": "CJ 1",
  "address_neighborhood": "Centro",
  "address_zip_code": "01005000",
  "address_city": "São Paulo",
  "address_state": "SP",
  "billing_amount": "15000",
  "payment_number": "11111999999999-1",
  "payment_method": "bolepix",
  "payment_status": "cancelled",
  "payment_substatus": "",
  "payment_amount": 15000,
  "description": "Cobrança 1111100000 - parcela 001/001",
  "installment": "1/1",
  "fine": 0.0,
  "fees": 0.0,
  "discount_before_payment": "0.0",
  "discount_before_payment_due_date": 1681757667,
  "due_date": 1681959600,
  "issued_at": 1681781894,
  "integration_identifier": "1234",
  "os_code": "8888888888",
  "os_identifier": "5678",
  "nf_url": "https://nf.co/123098",
  "nfe_number": "",
  "danfe": "",
  "barcode_b64": "iVBORw0KGgo...",
  "boleto_url": "https://boletos.fitbank.com.br/pdf/2023-04-18/4044kt2s.pdf",
  "code": "45090.13781 00000.127805 00255.550032 1 94790000001295",
  "hash": "00030101021226780025br.gov.bcb.pix2556qrcode.fitbank.com.br/QR/cobv/...",
  "paid_amount": 0,
  "paid_at": 0,
  "payment_captured_at": 0,
  "paid_method": ""
}

Regras

barcode_b64: Disponível para pagamentos com boleto, nos eventos payments/registered, payments/overdue, payments/paid e payments/cancelled. Vazio ("") nos demais casos.

boleto_url: Mesmas regras de barcode_b64.

code: Mesmas regras de barcode_b64 (linha digitável).

hash: Disponível para pagamentos com PIX, nos eventos payments/registered, payments/overdue, payments/paid e payments/cancelled. Vazio ("") nos demais casos.

paid_amount: Valor efetivamente pago em centavos. Preenchido corretamente no evento payments/paid quando payment_substatus for "credited". Nos demais eventos, ou antes do crédito, será 0.

paid_at: Timestamp do pagamento. Preenchido no evento payments/paid; 0 quando não pago.

payment_substatus: Indica o estágio complementar do pagamento. O valor "credited" confirma que o valor foi creditado — use em conjunto com payment_status: "paid" para baixa definitiva.

payment_captured_at: Timestamp da captura do pagamento; 0 quando não aplicável.

paid_method: Meio efetivo do pagamento (pix ou boleto). Preenchido no evento payments/paid.

recipient_bank_internal_number: Identificador bancário interno; presente em alguns pagamentos e omitido no evento payments/created.

danfe: Retornado quando disponível (comum em integrações ERP).

integration_identifier: Identificador de integração ERP.

is_renegotiation / renegotiation_type / renegotiation_payments: Ver seção Renegociação e Acordos.

Tipos de Dados

Campo	Tipo	Formato
`due_date`	`integer`	Timestamp em segundos
`issued_at`	`integer`	Timestamp em segundos
`discount_before_payment_due_date`	`integer`	Timestamp em segundos (`0` se ausente)
`paid_at`	`integer`	Timestamp em segundos (`0` se ausente)
`payment_captured_at`	`integer`	Timestamp em segundos (`0` se ausente)
`billing_amount`	`string`	Valor em centavos de Real
`payment_amount`	`number`	Valor em centavos de Real
`paid_amount`	`integer`	Valor em centavos de Real
`discount_before_payment`	`string`	Valor decimal em reais (ex.: `"0.0"`, `"10.5"`)
`fine`	`number`	Percentual
`fees`	`number`	Percentual
`is_renegotiation`	`boolean`	`true` quando aplicável
`renegotiation_type`	`string`	Ex.: `AGREEMENT`
`renegotiation_payments`	`array` de `string`	Lista de IDs de parcelas originais

Possible Values

payment_substatus:
credited | (vazio — demais estágios ou não aplicável)

paid_method:
pix | boleto

renegotiation_type:
AGREEMENT | RENEGOTIATION (previsto) | (omitido — renegociação via portal interno)

Exemplos de headers

{
  "X-Neofin-Topic": "payments/created",
  "X-Neofin-Hmac-SHA256": "J6ODFwjCaimneCz3l84pHNe2KPf51253wUr/jCdHx/s=",
  "X-Neofin-Webhook-ID": "9ad62e77-9036-328e-f789-30661934c63c",
  "X-Neofin-Datetime": "2023-04-17T22:38:15-03:00",
  "X-Neofin-API-Version": "2023-01",
  "User-Agent": "neofin-webhook"
}

Header	Descrição
`X-Neofin-Topic`	Tópico do evento: `payments/created` \| `payments/registered` \| `payments/overdue` \| `payments/paid` \| `payments/cancelled`
`X-Neofin-Hmac-SHA256`	Assinatura HMAC da requisição, usada para validar a autenticidade
`X-Neofin-Webhook-ID`	ID único da requisição. Use para evitar processar webhooks duplicados
`X-Neofin-Datetime`	Data/hora da entrega no formato ISO 8601 (timezone `America/Sao_Paulo`)
`X-Neofin-API-Version`	Versão da API. Atualmente: `2023-01`
`User-Agent`	Sempre `neofin-webhook`

Validação do Webhook

A assinatura é gerada usando o corpo da requisição (payload JSON serializado) + sua Secret Key, utilizando o algoritmo HMAC-SHA256. O resultado é codificado em Base64.

Como preparar seus webhooks - Atualizado

Endpoint para Recebimento de Webhooks#

Política de Reenvio (Retry Policy)#

Registro de Webhooks#

API#

Eventos disponíveis para registro no topic#

Como os eventos são disparados#

Diferença entre payments/created e payments/registered#

payment_status retornados por tópico#

payments/created#

payments/registered#

payments/overdue#

payments/paid#

Regras do evento payments/paid#

payments/cancelled#

Renegociação e Acordos#

Contexto#

Campos de renegociação no payload#

Regras de inclusão#

Valores de renegotiation_type#

O que são os IDs em renegotiation_payments?#

Modelo de relacionamento#

Como usar os campos no integrador#

Identificar a parcela do evento#

Identificar as parcelas originais renegociadas#

Exemplo de payload com renegociação (payments/created)#

Exemplo de renegociação via portal interno (sem tipo)#

Webhooks das parcelas originais#

Referência completa de campos do payload#

Campos base (todos os tópicos)#

Campos condicionais#

Exemplos de Payload/JSON#