Arquitetura de Webhooks

Envelope Padronizado

Todo webhook chega com a seguinte estrutura:

{
  "eventType": "CREDIT_OPERATION_CREATED",
  "entityId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "occurredAt": "2026-09-28T14:30:00Z",
  "data": { }
}

Campo	Tipo	Descrição
`eventType`	string (enum)	Identificador do tipo do evento disparado.
`entityId`	uuid	ID interno da entidade associada ao evento (operação de crédito, conta escrow, etc.).
`occurredAt`	datetime	Timestamp UTC (ISO 8601) do instante em que o evento ocorreu.
`data`	object	Dados completos do evento e da entidade associada.

Autenticidade e Assinatura HMAC-SHA256

Toda requisição enviada pelo LaaS inclui o header:

X-Laas-Webhook-Signature: sha256=<hmac-hex>

A assinatura é o HMAC-SHA256 gerado a partir do corpo bruto (raw body) da requisição com o secret compartilhado na ativação do parceiro. Sempre valide a assinatura antes de processar qualquer webhook.

Catálogo de Eventos (18 Eventos)

1. Operações de Crédito

Evento	Disparado quando
`CREDIT_OPERATION_CREATED`	Uma nova operação de crédito é criada com sucesso (`RECEIVED`).
`CREDIT_OPERATION_STATUS_CHANGED`	O status da operação transiciona via aprovação (`APPROVED`) ou cancelamento (`CANCELLED`).
`DISBURSEMENT_REQUESTED`	O desembolso do crédito é enviado para liquidação no sistema financeiro.
`DISBURSEMENT_COMPLETED`	O valor é liquidado com sucesso na conta ou chave Pix do tomador (`DISBURSED`).
`DISBURSEMENT_FAILED`	A liquidação bancária do desembolso falha ou é rejeitada.

2. Formalização e Assinatura de Contratos

Evento	Disparado quando
`CONTRACT_GENERATED`	A minuta do contrato é gerada com sucesso pela esteira ou anexada via upload externo.
`CONTRACT_GENERATION_FAILED`	A geração da minuta falhou por erro interno ou indisponibilidade.
`CONTRACT_SIGNING_REQUESTED`	Convites de assinatura eletrônica enviados aos signatários (`CONTRACT_SIGNING_PENDING`).
`CONTRACT_SIGNED`	Contrato assinado por todos os signatários ou validado por manifesto de fingerprint.
`FINGERPRINT_RECEIVED`	Manifesto auditável de evidências de assinatura externa validado com sucesso.

3. Servicing & Cobranças (Billing)

Evento	Disparado quando
`BILLING_CREATED`	Nova cobrança Pix gerada para a operação via `POST .../billings`.
`BILLING_PAID`	Cobrança Pix paga e liquidada pela instituição financeira recebedora.
`INSTALLMENT_PARTIALLY_PAID`	Parcela amortizada parcialmente via `POST .../payments`.
`INSTALLMENT_LIQUIDATED`	Parcela totalmente quitada/liquidada.
`PAYMENT_PLAN_LIQUIDATED`	Plano de pagamento integralmente liquidado (todas as parcelas pagas).
`INSTALLMENT_PAYMENT_FAILED`	Falha na tentativa de pagamento ou conciliação assíncrona da parcela via Pix.

4. KYC e Conta Escrow

Evento	Disparado quando
`KYC_REQUESTED`	Análise de KYC iniciada para a operação de crédito.
`ESCROW_ACCOUNT_CREATED`	Conta escrow provisionada e aberta no sistema bancário.

Boas práticas

Responda rápido: retorne 2xx assim que receber e enfileirar o evento — processe de forma assíncrona, sem bloquear a resposta.
Idempotência do lado do consumidor: o mesmo evento pode, em cenários raros de retry, ser entregue mais de uma vez — use entityId + eventType + occurredAt para deduplicar.
Disponibilidade: mantenha a URL do webhook sempre disponível; entregas com falha podem ser reenviadas, mas indisponibilidade prolongada pode levar à perda de eventos.