Catálogo de eventos

1. Envelope

Hoje a IORQ envia um único message_type: LOAN_UPDATE. O corpo do POST para a sua URL é o objeto payload acrescido de iorq_fund_id no topo, com esta forma:

{
  "event": "update",
  "data": {
    "entity_id": "<originator_proposal_code>",
    "status": "<status — ver abaixo>",
    "reason": "<motivo, quando aplicável>",
    "nosso_numero": "<quando aplicável>",
    "installment_code": "<quando aplicável>",
    "banker_proposal_code": "<quando aplicável>",
    "entity_type": "ccb",
    "due_date": "<quando aplicável — nova data de vencimento (ISO)>"
  },
  "iorq_fund_id": "374485cf-f6df-467c-b91d-9f14082c6f36"
}

O discriminador do que aconteceu é data.status. Os demais campos de data variam conforme o status (podem vir nulos/ausentes). Não há um evento por transição de estado — tudo chega como LOAN_UPDATE.

2. `iorq_fund_id` no corpo

Toda entrega traz iorq_fund_id no topo do corpo — o UUID do fundo a que o evento pertence, o mesmo informado no registro do webhook (header iorq-fund-id). Quem integra mais de um fundo passa a poder rotear pelo próprio corpo, sem depender de uma URL distinta por fundo. O prefixo iorq_ marca o campo como acrescentado pela IORQ na entrega, e não como parte do payload do evento.

O valor é o do evento registrado na IORQ. Se o seu webhook estiver registrado para o fundo A, todo corpo entregue nele traz o iorq_fund_id do fundo A.
O campo entra no corpo antes da assinatura, então o HMAC cobre o corpo com iorq_fund_id. A validação não muda: calcule o digest sobre os bytes exatos recebidos, como já fazia (ver Configuração e segurança).
Consumidores que ignoram campos desconhecidos não precisam de nenhuma mudança. Se o seu parser rejeita campos extras (additionalProperties: false ou equivalente), libere iorq_fund_id.

3. Valores de `data.status`

Cessão

`status`	Quando dispara
`approved`	Operação aprovada na elegibilidade
`rejected`	Operação recusada — esquemática ou de negócio (ver `data.reason`)
`invalid`	Falha de validação / estado inválido

Liquidação

`status`	Quando dispara
`settled_installment`	Parcela liquidada com sucesso
`received_prepayment`	Liquidação antecipada aceita
`invalid`	Falha (estado inválido, valor divergente, conciliação) — ver `data.reason`

Pós-cessão

`status`	Quando dispara
`approved`	Recompra aprovada
`rejected`	Recompra ou renegociação recusada
`approved_renegotiation`	Renegociação aprovada (nova operação na carteira)
`invalid_renegotiation`	Falha na renegociação

Alteração de vencimento

`status`	Quando dispara
`due_date_changed`	Nova data de vencimento em vigor no boleto da parcela — emitido apenas quando a cobrança da operação é de responsabilidade da IORQ (sem cobrança IORQ não há boleto, e a alteração é registrada só na administradora). Um webhook por parcela alterada, com a nova data em `data.due_date` e a parcela em `data.installment_code`. Ver Alteração de vencimento

4. `data.reason`

Em status de recusa/falha, data.reason traz o motivo — pode ser uma string ou um objeto. Exemplos observados: fund_not_found, banker_not_found, loan_not_found, invalid_loan_state, invalid_installment_state, settlement_conciliation_error, value_mismatch (...), além dos códigos de elegibilidade definidos por fundo na homologação.

5. Sem filtro por tipo de evento

Você recebe todos os LOAN_UPDATE do fundo registrado. Não há assinatura por tipo de evento nem curinga * — o filtro é feito no seu lado, pelo data.status.

6. Próximos passos

Continuar — Idempotência e reentrega

O que acontece quando você não consegue processar.

Mapa de estados — Ciclo de vida

Veja como cada mudança de status se relaciona aos estados.