Tipos de evento em detalhe

O Catálogo de eventos descreve o envelope e lista os tipos numa tabela. Esta página explica cada tipo, um por um, a partir do serviço que o emite. Leia-a quando for decidir o que o seu sistema faz com cada type.

Os verbetes seguem o mesmo roteiro: quando o fato acontece, sujeito do envelope, o que data garante, o motivo quando existe, o equivalente v1, o que vem antes e depois, e o que fazer. Os campos citados são os do envelope v2; para o corpo legado, veja Contrato v1 (legado).

1. Como os tipos se encadeiam

O caminho de uma operação, do envio à baixa, gera esta sequência quando tudo dá certo:

flowchart LR
    P[POST /loan/] --> E{Elegibilidade}
    E -- falha --> LI[loan.invalid]
    E -- passa, em silêncio --> L[Lote de aquisição]
    L -- gestor aprova --> LA[loan.approved]
    L -- gestor recusa --> LR[loan.rejected]
    LA --> AC[acquisition.completed]
    AC --> CI[charge.issued]
    CI --> IS[installment.settled]
    IS --> SC[installment.settlement_completed]

Três regras valem para a leitura de qualquer verbete:

• Elegibilidade aprovada não gera evento. Só a falha gera (loan.invalid). A primeira notícia positiva de uma operação é o loan.approved, que vem quando o gestor aprova o lote, não quando a validação passa.
• Aprovação e recusa são do recurso que você pediu. A cessão usa loan.approved e loan.rejected; a recompra, repurchase.approved e repurchase.rejected; a renegociação, renegotiation.approved e renegotiation.rejected. No corpo v1 a cessão e a recompra dividem approved e rejected; só o v2 os distingue.
• Todo fato confirmado pela administradora tem sufixo .completed. Ele é a palavra final: antes dele a IORQ já processou, mas a administradora ainda não confirmou. Entre um e outro passam horas ou dias.
• Cada chamada tem o seu tipo de falha. loan.invalid é só a cessão: a operação reprovou e ficou em invalid. A liquidação que a IORQ não consegue aplicar volta como installment.settlement_invalid, a antecipação como prepayment.invalid, a recompra como repurchase.invalid e a renegociação como renegotiation.invalid. Nesses quatro a operação segue no estado anterior; só na cessão a falha é terminal, com uma exceção descrita em loan.invalid: o arquivo de lastro ou o dado de operação não aceito.

2. Operação (loan.*)

loan.approved

• Quando: o gestor do fundo aprova o lote de aquisição em que a operação está, e ela é enviada à administradora. Um evento por operação aprovada no lote. É só da cessão: a aprovação de uma recompra tem tipo próprio, repurchase.approved.
• Sujeito: loan; subject.id é o originator_code.
• data: loan (originator_code, kind). Sem installment, sem charge, sem motivo.
• v1: approved.
• Antes: POST /loan/ respondeu 201 e a elegibilidade passou em silêncio.
• Depois: acquisition.completed, quando a administradora confirmar a cessão.

O que fazer. Marque a operação como aprovada pelo fundo e aguarde a confirmação. Não trate como cedida: a cessão só se materializa no acquisition.completed.

loan.rejected

• Quando: alguém disse não à operação antes da administradora entrar em cena. Quatro origens: o gestor recusa o lote de aquisição inteiro; o gestor aprova o lote mas a operação não estava em estado aprovável, e sobra de fora; o gestor recusa um lote de renegociação antes de aprová-lo, e cada operação nova do lote recebe loan.rejected; ou você mesmo recusou a operação com POST /loan/reject, e a IORQ ecoa a recusa. A recusa de uma recompra tem tipo próprio, repurchase.rejected. Um caso especial vem da renegociação: quando um lote de renegociação reprova em covenant do fundo, cada operação do lote recebe loan.rejected (não renegotiation.rejected) com o código E026.
• Sujeito: loan.
• data: loan. Motivo normalmente ausente: nas recusas do lote de aquisição e no eco do POST /loan/reject, errors e reason_text chegam nulos; na recusa de um lote de renegociação, errors chega como lista vazia ([]), sem motivo a declarar. A exceção é a reprovação em covenant, que traz errors[] com E026 e o título "Renegociação Reprovada em Covenant".
• v1: rejected.
• Antes: loan.approved nunca veio, ou a operação estava num lote em análise.
• Depois: nada. É terminal para aquela originator_code; uma nova tentativa é uma nova cessão, com outro código.

O que fazer. Encerre a operação do seu lado. Não espere motivo no evento: se precisar dele, a recusa do gestor é registrada na IORQ e chega por canal humano, não por webhook. Trate o eco do seu próprio POST /loan/reject como confirmação, não como novidade.

loan.invalid

• Quando: a operação enviada em POST /loan/ reprovou na validação da IORQ e ficou em invalid: elegibilidade do fundo, fundo ou bancarizador não encontrados, código de proposta duplicado, ou um erro inesperado ao processá-la (unexpected_error_processing_operation). É um fato da cessão: a falha de liquidação, antecipação e recompra tem tipo próprio (installment.settlement_invalid, prepayment.invalid, repurchase.invalid).
• Sujeito: loan.
• data: loan e um motivo garantido. Os motivos operacionais (fund_not_found, fund_not_supported, banker_not_found, duplicated_originator_proposal_code, unexpected_error_processing_operation) chegam em errors[] com um code do catálogo. A elegibilidade reprovada chega como o mapa {"E0xx": {...}} serializado em reason_text, com errors nulo e banker_code nulo; leia-o como JSON.
• Exceção: a recepção de arquivo de lastro (POST /loan/files) e a atualização de dados da operação (PATCH /loan/operation-data) também emitem loan.invalid, com unexpected_error_processing_operation e o texto do erro na description, quando o pedido não é aceito (operação não encontrada, tipo de documento não permitido, payload inválido). Nesse caso a operação não vai a invalid e não é terminal: corrija o pedido e envie de novo.
• v1: invalid.
• Antes: o POST /loan/ que já tinha recebido 201.
• Depois: nada. É terminal para aquela originator_code: corrija e ceda de novo com outro código.

O que fazer. Encerre a operação do seu lado e corrija o que o motivo aponta, salvo na exceção acima, em que a operação segue viva. Alerte operação humana quando o motivo começar com unexpected_error.

⚠️

O que mudou

Até esta versão do contrato, a falha de liquidação, antecipação e recompra também saía como loan.invalid (v1 invalid), e só dava para distinguir a cessão das demais pela presença de installment e pelo formato do motivo. Cada uma tem agora o seu tipo. Um consumidor v2 que tratava toda falha em loan.invalid precisa passar a tratar também installment.settlement_invalid, prepayment.invalid e repurchase.invalid. No v1 a adoção é por webhook: o campo v1_failure_status decide se as três chegam como invalid_settlement, invalid_prepayment e invalid_repurchase (per_context) ou como invalid (shared_invalid, o que um webhook antigo recebe até você trocar). Ver Contrato v1 (legado).

3. Aquisição (acquisition.*)

acquisition.completed

• Quando: a administradora confirmou a aquisição do lote. A operação passa a active, as parcelas a active e o lote a acquired. Um evento por operação.
• Sujeito: loan.
• data: loan.
• v1: acquisition_completed.
• Antes: loan.approved, normalmente horas antes; a espera é o processamento da administradora.
• Depois: charge.issued para cada parcela, quando a cobrança é da IORQ. A partir daqui a operação está na carteira do fundo e é liquidável.

O que fazer. Este é o fato que vale como cessão efetivada: contabilize, libere o que depende do desembolso e passe a aceitar liquidações da operação. Se a operação some da sua fila de "aguardando" sem este evento, consulte GET /loan/ antes de assumir perda: o evento pode ter caído em reentrega.

acquisition.expired

Tipo reservado no contrato, sem produtor hoje. Existe para que a IORQ possa reconstruir mensagens antigas; nenhuma integração deve esperar recebê-lo. Se aparecer, o sujeito é o fundo (credit_vehicle), não uma operação.

4. Parcela (installment.*)

installment.settled

• Quando: a IORQ registrou o pagamento de uma parcela. Três caminhos: você notificou com POST /installment/settle; o banco confirmou o pagamento do boleto de cobrança IORQ; ou uma antecipação aceita cobriu a parcela, e então vem um evento por parcela coberta. É o primeiro tempo da baixa: a IORQ já considera a parcela paga, a administradora ainda não.
• Sujeito: installment; subject.id é o identificador da parcela na IORQ.
• data: loan e installment (id, number). charge.nosso_numero quando havia boleto IORQ por trás. reason_text vem preenchido com uma confirmação em texto (installment settled successfully): não o leia como erro.
• v1: settled_installment.
• Antes: acquisition.completed; e charge.issued da parcela, quando a cobrança é da IORQ.
• Depois: installment.settlement_completed, quando a administradora confirmar, em geral no dia útil seguinte ou depois.

O que fazer. Marque a parcela como paga do seu lado. Se você repetir POST /installment/settle de uma parcela já liquidada, a resposta é installment.settlement_invalid com invalid_installment_state, não um segundo installment.settled.

installment.settlement_completed

• Quando: a administradora confirmou a baixa da parcela. Ela vai a settled. Numa baixa parcial, a parcela volta a active com o saldo remanescente. Um evento por parcela.
• Sujeito: installment.
• data: loan; installment (id, number, due_date) quando o produtor publica em v2. Enquanto o fato é publicado em v1 e convertido na entrega, o caso de produção hoje, installment chega nulo e o sujeito vira a operação: veja o aviso no Catálogo de eventos.
• v1: settlement_completed, um corpo por operação, sem os campos de parcela.
• Antes: installment.settled. Os dois nascem em serviços diferentes e viajam por filas diferentes: receber este sem ter visto o primeiro não significa que o primeiro se perdeu.
• Depois: nada para a parcela. Quando a última parcela chega aqui, a operação vai a settled.

O que fazer. Dê a baixa contábil definitiva. Se o seu processo só precisa saber que a parcela foi paga, installment.settled basta e este evento pode ser ignorado; se ele precisa da confirmação da administradora, espere por este.

installment.settlement_invalid

• Quando: a IORQ não aplicou a liquidação que você notificou em POST /installment/settle. Motivos: a parcela não foi encontrada (installment_not_found), já estava liquidada ou fora de estado liquidável (invalid_installment_state), o valor não conciliou (settlement_conciliation_error), ou um erro inesperado (unexpected_error_settling_installment). Um evento por notificação que falhou.
• Sujeito: installment quando a IORQ identificou a parcela; loan quando não (parcela não encontrada, erro antes de resolvê-la).
• data: loan, o motivo garantido em errors[] (code do catálogo, description com o detalhe), e installment (number, e id quando resolvido) com o code que você enviou. charge.nosso_numero acompanha quando havia boleto.
• v1: invalid_settlement.
• Antes: o POST /installment/settle que já tinha recebido 201.
• Depois: a parcela segue no estado em que estava, com uma exceção: settlement_conciliation_error a marca nesse estado, para conciliação manual pela IORQ. Nos demais motivos, corrija e repita a notificação.

O que fazer. Não marque a parcela como paga. Correlacione pelo installment.number (o code da chamada) e pelo loan.originator_code; invalid_installment_state numa parcela que você já viu em installment.settled é uma notificação repetida, não um problema. Alerte operação humana quando o motivo começar com unexpected_error.

installment.due_date_changed

• Quando: a nova data de vencimento que você pediu em PATCH /installment/due-date está em vigor no boleto do bancarizador. Um evento por parcela alterada. Só existe quando a cobrança da operação é da IORQ: sem boleto IORQ, a resposta síncrona do PATCH é a única confirmação.
• Sujeito: installment.
• data: loan, installment com due_date obrigatório (a nova data), charge.nosso_numero do boleto atualizado.
• v1: due_date_changed.
• Antes: o PATCH respondeu 200; entre a resposta e este evento, a carteira da IORQ já tem a data nova e o boleto do tomador ainda pode mostrar a antiga.
• Depois: o ciclo normal da parcela, com o novo vencimento.

O que fazer. Só comunique a nova data ao tomador depois deste evento. A mesma parcela pode ser alterada mais de uma vez dentro da janela permitida, e cada alteração gera um evento com idempotency_key diferente, porque a chave leva o vencimento.

5. Antecipação (prepayment.*)

prepayment.received

• Quando: a IORQ aceitou o pedido de liquidação antecipada de POST /installment/prepayment/v2, que pode cobrir parcelas de mais de uma operação do mesmo tomador. Um evento por pedido, não por parcela.
• Sujeito: loan, a primeira operação do pedido; as demais não aparecem no envelope.
• data: loan da primeira operação; installment.number é o code que você definiu para a nova parcela de antecipação dessa operação. reason_text traz uma confirmação em texto (multi-loan prepayment received successfully).
• v1: received_prepayment.
• Antes: o POST respondeu 201.
• Depois: charge.issued do boleto do lote de antecipação, com installment.number igual a 99; quando o tomador paga, um installment.settled por parcela coberta, em todas as operações do pedido. Se uma parcela alvo for liquidada por outro caminho antes disso, a antecipação aberta que a cobria é cancelada e o boleto dela recebe charge.cancelled.

O que fazer. Registre o pedido como aceito e guarde a relação entre o code da antecipação e as parcelas cobertas, porque o evento não a repete. A falha do pedido não vem neste tipo: vem como prepayment.invalid.

prepayment.invalid

• Quando: a IORQ não aceitou o pedido de POST /installment/prepayment/v2. Motivos: operação ou parcela não encontrada (loan_not_found, prepayment_installments_not_found), operações de tomadores diferentes (all_loans_must_belong_to_same_customer_person), lista vazia ou códigos repetidos, parcela fora de estado antecipável (installments_not_prepayable), soma divergente (total_prepayment_amount_mismatch) ou abaixo do valor das parcelas (prepayment_amount_below_installment_values), e erro inesperado (unexpected_error_prepaying_installment). Um evento por pedido.
• Sujeito: loan, a primeira operação do pedido, como em prepayment.received.
• data: loan da primeira operação, o motivo garantido em errors[] (code do catálogo, description com os identificadores que não bateram), e installment.number com o code da antecipação dessa operação.
• v1: invalid_prepayment.
• Antes: o POST que já tinha recebido 201.
• Depois: nada muda: nenhuma parcela foi antecipada e nenhum boleto foi emitido. Corrija e repita o pedido.

O que fazer. Descarte o pedido do seu lado e decida pelo code; a description lista os identificadores que não bateram. Nenhuma parcela coberta pelo pedido mudou de estado.

6. Cobrança (charge.*)

Os fatos de cobrança só existem quando a cobrança da operação é da IORQ. Fundo cuja cobrança é do próprio originador nunca recebe charge.*.

charge.issued

• Quando: o bancarizador emitiu o boleto (bolecode) de uma parcela ou do lote de uma antecipação.
• Sujeito: installment. Para o boleto de antecipação, subject.id é o identificador da antecipação e installment.number é 99: não é a parcela 99.
• data: loan, installment e charge são garantidos. charge.kind é boleto; charge.nosso_numero identifica o título no banco; charge.banker_response traz a resposta crua do bancarizador, serializada.
• v1: issued_bolecode.
• Antes: acquisition.completed (boleto de parcela) ou prepayment.received (boleto de antecipação).
• Depois: installment.settled quando pago; charge.cancelled se o título for cancelado antes; installment.due_date_changed se o vencimento mudar.

O que fazer. Guarde o nosso_numero junto da parcela: é a chave para conciliar o pagamento e para citar o título num chamado. Não recalcule nada a partir de banker_response; ele existe para auditoria.

charge.cancelled

• Quando: o boleto de uma parcela ou de uma antecipação foi cancelado no bancarizador. Acontece quando a parcela é substituída por recompra ou renegociação, quando a antecipação que o boleto cobrava deixa de valer, ou quando a IORQ cancela o título por operação.
• Sujeito: installment (ou a antecipação, como em charge.issued).
• data: loan, installment e charge garantidos, com o nosso_numero do título cancelado. Sem banker_response.
• v1: canceled_bolecode.
• Antes: o charge.issued do mesmo nosso_numero.
• Depois: depende da causa: repurchase.completed, renegotiation.completed, ou um novo charge.issued para a mesma parcela.

O que fazer. Invalide o título do seu lado e retire o boleto de qualquer canal em que você o apresente ao tomador. Um pagamento que chegue depois do cancelamento não vira installment.settled por este título.

7. Recompra (repurchase.*)

repurchase.approved

• Quando: o gestor do fundo aprova o pedido de POST /loan/repurchase e a recompra segue para a administradora. Um evento por operação aprovada no pedido, e só na primeira submissão do pedido: um reenvio à administradora depois de erro não repete o evento.
• Sujeito: loan.
• data: loan. Sem motivo.
• v1: approved, o mesmo valor da aprovação de cessão. No corpo legado os dois fatos são indistinguíveis; é o v2 que os separa.
• Antes: POST /loan/repurchase respondeu 201.
• Depois: repurchase.completed, quando a administradora confirmar.

O que fazer. Marque a recompra como aceita pelo fundo e aguarde. A operação continua na carteira cedida até o repurchase.completed.

📘

Decisão de recompra registrada antes de 28/09/2026

Reentregue ou reenviada por replay, ela ainda chega como loan.approved ou loan.rejected. Só afeta quem pediu recompra antes dessa data; a ressalva está descrita no Catálogo de eventos.

repurchase.rejected

• Quando: o gestor recusa o pedido de recompra; ou aprova o pedido e uma operação dele já estava recusada (o gestor a tinha recusado antes, na revisão do pedido), e ela recebe este evento em vez de repurchase.approved. Operações do pedido em outros estados são puladas na aprovação, sem evento. Dentro da aprovação, os dois tipos só saem na primeira submissão do pedido. Um evento por operação recusada.
• Sujeito: loan.
• data: loan. Sem motivo: errors e reason_text chegam sempre nulos.
• v1: rejected, o mesmo valor da recusa de cessão.
• Antes: POST /loan/repurchase respondeu 201.
• Depois: nada. A operação segue na carteira, como estava antes do pedido.

O que fazer. Encerre o pedido de recompra do seu lado e mantenha a operação ativa. Um novo pedido é um novo POST.

repurchase.completed

• Quando: a administradora confirmou a recompra. A operação vai a repurchased, as parcelas também. Um evento por operação.
• Sujeito: loan.
• data: loan.
• v1: repurchase_completed.
• Antes: POST /loan/repurchase respondeu 201, o gestor aprovou (repurchase.approved) e a operação foi enviada à administradora. Se o gestor recusou, veio repurchase.rejected e este evento não vem. Se a IORQ não conseguiu processar o pedido, veio repurchase.invalid.
• Depois: charge.cancelled dos boletos em aberto da operação, quando a cobrança é da IORQ. É terminal para a operação.

O que fazer. Retire a operação da carteira cedida e encerre as parcelas em aberto. Só aqui a recompra está concluída: a aprovação anterior era a do gestor, não a liquidação financeira.

repurchase.invalid

• Quando: a IORQ não aceitou o pedido de POST /loan/repurchase. Motivos: operação não encontrada (loan_not_found), operação fora de estado recomprável (invalid_loan_state), valor de recompra abaixo do valor na curva (value_mismatch, só nos fundos cuja recompra confere o valor) ou erro inesperado (unexpected_error_repurchasing). Um evento por operação do pedido que falhou.
• Sujeito: loan.
• data: loan e o motivo garantido em errors[] (code do catálogo). Sem installment.
• v1: invalid_repurchase.
• Antes: o POST /loan/repurchase que já tinha recebido 201.
• Depois: nada muda: a operação segue no estado anterior, sem pedido de recompra aberto. Corrija e repita.

O que fazer. Não retire a operação da carteira. Se o motivo for invalid_loan_state, consulte GET /loan/ antes de repetir: a operação pode já estar em outro fluxo (renegociação, baixa) que impede a recompra.

8. Renegociação (renegotiation.*)

Uma renegociação cria uma nova operação, com originator_proposal_code próprio, que substitui uma ou mais operações antigas. Os quatro fatos abaixo têm como sujeito a operação nova; loan.kind vem como cd.

renegotiation.approved

• Quando: a nova operação foi aprovada para seguir. Duas origens: a avaliação automática do lote de renegociação, quando o lote é pré-aprovado; ou a aprovação manual do gestor no lote. Um evento por operação nova.
• Sujeito: loan (a operação nova).
• data: loan. errors[] pode vir como lista vazia: significa "sem motivo a declarar", não erro.
• v1: approved_renegotiation.
• Antes: PATCH /loan/renegotiate respondeu 201.
• Depois: renegotiation.completed, quando a administradora confirmar. Se o tomador não concluir a assinatura em cerca de dez dias, a pré-aprovação expira e vem renegotiation.invalid no lugar.

O que fazer. Trate como "renegociação aceita, aguardando formalização". As operações antigas continuam ativas até o renegotiation.completed.

renegotiation.rejected

• Quando: ao aprovar o lote de renegociação, a operação nova não estava pré-aprovada nem inválida, e ficou de fora. Em geral porque ela já tinha sido recusada na revisão anterior. Não confundir com a reprovação em covenant, que chega como loan.rejected com E026.
• Sujeito: loan (a operação nova).
• data: loan; errors[] vazio.
• v1: rejected_renegotiation.
• Antes: PATCH /loan/renegotiate respondeu 201.
• Depois: nada. As operações antigas seguem como estavam.

O que fazer. Encerre a operação nova do seu lado e mantenha as antigas ativas. Uma nova tentativa é um novo PATCH, com outro código.

renegotiation.invalid

• Quando: a renegociação não pôde ser processada. Origens: falha de elegibilidade da nova operação na entrada; motivo operacional na entrada (renegotiation_already_processed, renegotiation_loans_not_found e os demais da seção 5 do catálogo); documento de renegociação reprovado na validação (E024); pré-aprovação expirada por falta de assinatura (E023); reprovação na avaliação do lote de renegociação; erro inesperado (unexpected_error_renegotiating).
• Sujeito: loan (a operação nova).
• data: loan e o motivo, em um de dois campos. Em errors[]: os motivos operacionais, com um code do catálogo, e os E0xx do lote de renegociação (a avaliação do lote, e a aprovação ou recusa do lote pelo gestor, que repetem o resultado de validação gravado na operação). Em reason_text, como o mapa {"E0xx": {...}} serializado: a elegibilidade na entrada, o E023 e o E024. Diferente de loan.invalid, o motivo não é garantido pelo esquema: trate os dois campos como opcionais.
• v1: invalid_renegotiation.
• Antes: PATCH /loan/renegotiate respondeu 201; na expiração, veio renegotiation.approved antes.
• Depois: nada. As operações antigas seguem ativas.

O que fazer. Encerre a operação nova. Se o motivo for expiração, a renegociação precisa ser refeita do zero; se for validação, corrija e reenvie com outro código.

renegotiation.completed

• Quando: a administradora confirmou a renegociação. A operação nova vai a active; as antigas vão a renegotiated. Um evento por operação nova.
• Sujeito: loan (a operação nova).
• data: loan.
• v1: renegotiation_completed.
• Antes: renegotiation.approved.
• Depois: charge.cancelled dos boletos das operações antigas e charge.issued das parcelas da nova, quando a cobrança é da IORQ. A operação nova entra no ciclo normal.

O que fazer. Substitua as operações antigas pela nova na sua carteira. Este evento não lista as antigas: use o que você enviou em renegotiated_loans[] no PATCH.

9. Teste (webhook.*)

webhook.test

• Quando: você pediu em POST /api/webhook/{webhook_id}/test. Só esse webhook recebe; os outros webhooks do fundo não. O evento é endereçado ao webhook e não passa pelo filtro event_types: chega mesmo num webhook que assina só installment.*, e é por isso que ele serve para testar qualquer webhook.
• Sujeito: credit_vehicle; subject.id é o fund_id.
• idempotency_key: webhook.test:credit_vehicle:<fund_id>:<event_id>, com o event_id que a chamada devolveu. Cada chamada gera uma chave nova, num webhook v1 ou v2: um teste nunca é deduplicado contra o anterior.
• data: vazio: loan, installment, charge, errors e reason_text nulos.
• v1: test, com entity_id igual ao fund_id e nenhum outro campo em data. O corpo entregue a um webhook v1 é {"event": "update", "data": {"entity_id": "<fund_id>", "status": "test"}, "iorq_fund_id": "<fund_id>", "event_timestamp": "<ISO-8601>"}, com os dois campos do topo injetados na entrega como em todo v1.
• Antes: a chamada respondeu 202 com o event_id.
• Depois: nada. O evento percorre a entrega normal: aparece em GET /api/events/webhook/{webhook_id}, gera tentativas em GET /api/attempts/event/{event_id}, é retentado e pode ser reenviado como qualquer outro.

O corpo entregue a um webhook v2, gerado com as mesmas classes que o serviço usa (o event_id da chamada aparece no fim da chave):

{
  "id": "evt_01K4Q8ZJ0000000000000000AW",
  "type": "webhook.test",
  "schema_version": "2026-10-01",
  "occurred_at": "2026-09-02T18:33:20.123456Z",
  "fund": {
    "id": "374485cf-f6df-467c-b91d-9f14082c6f36",
    "name": "FIDC EXEMPLO"
  },
  "subject": {
    "type": "credit_vehicle",
    "id": "374485cf-f6df-467c-b91d-9f14082c6f36"
  },
  "idempotency_key": "webhook.test:credit_vehicle:374485cf-f6df-467c-b91d-9f14082c6f36:01K4Q8ZJ0000000000000000WT",
  "data": {
    "loan": null,
    "installment": null,
    "charge": null,
    "errors": null,
    "reason_text": null
  }
}

O que fazer. Valide a assinatura, responda 2xx e confira a tentativa no histórico. Ignore o evento no seu processamento de negócio: um consumidor que só conhece a lista de tipos de operação deve tratá-lo como tipo desconhecido, sem erro. Limite de 10 por webhook na última hora, em janela deslizante contada pelos webhook.test criados: o 11º dentro de 60 minutos do 1º recebe 429, e a vaga volta quando o mais antigo completar uma hora, não na virada do relógio.

10. Resumo por pergunta

11. Próximos passos