Registrar URL de webhook

post

https://webhook-sender-manager-production.iorq.com.br/api/webhook

Registra uma URL HTTPS que receberá os eventos LOAN_UPDATE do fundo informado no header iorq-fund-id. Escolha no corpo a contract_version (v2, o envelope tipado, é o padrão; v1, o corpo legado, segue aceito quando enviado explicitamente) e os event_types que este webhook recebe. O webhook pertence à credencial que o registrou: outras credenciais do mesmo fundo não o veem em GET, e cada credencial com webhook ativo recebe a sua própria entrega de cada fato. A resposta é 200 (não 201) e inclui o standard_webhooks_secret, com o qual se valida a assinatura Standard Webhooks (webhook-signature) de cada entrega, e o mesmo segredo no formato da assinatura legada, o signing_secret (X-IORQ-Signature) — os dois expostos apenas nesta resposta. Os headers custom registrados são reenviados em cada entrega como camada adicional de autenticação. A URL precisa responder diretamente: a IORQ não segue redirect, e um 3xx conta como falha e entra na reentrega. Omitido max_attempts, o webhook segue a política da IORQ (hoje 11 tentativas em cerca de 70 h), e a resposta mostra o valor que vale.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

message_type

string

enum

required

Tipo de mensagem assinada. Hoje apenas LOAN_UPDATE

Allowed:

webhook_url

uri

required

URL HTTPS pública que receberá os eventos

headers

object

Headers custom reenviados em cada entrega. Use um header secreto para autenticar a origem. Até 32, nome como token da RFC 9110, valor sem caractere de controle e com até 4 KiB. Nomes proibidos, sem diferenciar maiúsculas (422): Host, Content-Length, Transfer-Encoding, Connection, Keep-Alive, TE, Trailer, Upgrade, Content-Type, webhook-id, webhook-timestamp, webhook-signature, Proxy- e X-IORQ-. Os valores são só de escrita: as respostas trazem apenas header_names

contract_version

string

enum

Defaults to v2

Versão do corpo entregue. v2 entrega o envelope tipado; v1 entrega o corpo legado {event, data}. Omitido, o webhook nasce v2 (até 19/10/2026 nascia v1); um webhook já registrado mantém a versão que tem

Allowed:

event_types

array of strings

Defaults to *

Tipos assinados: '', '.' (loan, acquisition, installment, prepayment, charge, repurchase, renegotiation, webhook) ou o tipo exato (ex.: installment.settled). O filtro vale para os fatos publicados em v2, qualquer que seja a contract_version do webhook; fatos ainda publicados em v1 chegam sem passar por ele. Lista vazia é recusada

event_types

v1_failure_status

string

enum

Defaults to per_context

Só para v1: como chega a falha de liquidação, antecipação e recompra. per_context entrega invalid_settlement / invalid_prepayment / invalid_repurchase; shared_invalid entrega as três como invalid, o comportamento anterior. Sem efeito em v2

Allowed:

max_attempts

integer

1 to 30

Tentativas de entrega por evento. Omitido, o webhook segue a política da IORQ e acompanha as mudanças dela

Headers

iorq-fund-id

uuid

required

UUID do fundo (credit vehicle). Entregue por e-mail na seção Fundos liberados quando a IORQ provisiona seu acesso. Obrigatório em toda chamada à API operacional (hs-receiver) e ao serviço de webhooks (webhook-sender-manager). Deve corresponder ao fund_id informado no corpo ou na query quando aplicável.

Responses

200Webhook registrado — única resposta que expõe o standard_webhooks_secret e o signing_secret. Devolve também a contract_version e os event_types gravados

400Header iorq-fund-id ausente, com formato inválido ou divergente do legado Fund-Id

401Header Authorization ausente. Token inválido ou expirado devolve 403, não 401

403Token inválido ou expirado (recusado no gateway, corpo {"message": "Forbidden"}); credencial sem acesso ao fundo do header iorq-fund-id; ou credencial sem a permissão desta operação (corpo {"detail": "..."}). A resposta é a mesma para fundo inexistente e fundo de outro cliente

409Esta credencial já tem um webhook com a mesma webhook_url para este fundo e message_type. Use PATCH para alterá-lo ou reativá-lo