Para times técnicos do piloto. O que está aqui é um resumo. Spec completa, credenciais e homologação saem com o time kroz em contato@kroz.co.

Webhooks

Como eventos de liquidação do parceiro BaaS alimentam conciliação, Rule Engine e auditoria.

Em resumo

Quando o pagador liquida uma cobrança (PIX ou boleto), o parceiro BaaS notifica a kroz. O processador:

Deduplica o evento (retries do parceiro não reprocessam)
Atualiza o status da operação de pagamento
Dispara settlement do Rule Engine quando aplicável
Enfileira sugestão de conciliação se houver divergência de valor

flowchart LR
    B[BaaS, liquidação] --> W[Webhook inbound kroz]
    W --> O[Operação atualizada]
    W --> R[Rule Engine]
    W --> C[Conciliação se divergir]

Autenticação

O endpoint inbound é público (sem cookie de operador), mas exige credencial dedicada no header, configurada apenas entre kroz, parceiro BaaS e time técnico do piloto.

Requisições inválidas retornam 401 sem detalhar o motivo.

Eventos relevantes

Categoria	O que a kroz faz
Cobrança criada	Marca operação como aguardando pagamento
Pagamento recebido	Settlement + checagem de valor
Pagamento confirmado	Consolida status final
Vencido / estornado	Atualiza trilha operacional
Split aplicado / divergência	Reflete estado do repasse na origem

O mapeamento exato depende do parceiro BaaS, o adaptador normaliza para o modelo interno.

Idempotência

Cada evento traz um identificador único. Se o parceiro reenviar o mesmo evento (retry de rede), a kroz responde sucesso sem duplicar efeitos colaterais.

Conciliação automática

Se o valor liquidado divergir do esperado (multa, desconto, arredondamento), o webhook alimenta a fila de conciliação com nível de confiança. O DF aprova ou rejeita, ver Conciliação.

Na prática

Rotacione credenciais de webhook ao trocar ambiente (sandbox → produção)
Monitore respostas 401 e 503 no painel do parceiro BaaS
Não exponha URLs de webhook em documentação pública ou repositórios