Arquitetura de Webhooks

Por que usar webhooks

Em vez de fazer polling repetido em GET /credit-operations/{externalContractId} (ou nos demais endpoints de consulta) para saber quando uma etapa mudou, assine os webhooks: cada evento relevante do ciclo de vida da operação, do documento ou da conta escrow dispara automaticamente uma notificação POST para a URL cadastrada pelo parceiro.

Envelope do evento

Todo webhook chega com a mesma estrutura:

{
  "eventType": "string",
  "entityId": "uuid",
  "occurredAt": "2026-08-06T12:00:00Z",
  "data": { }
}

Campo	Tipo	Descrição
`eventType`	string (enum)	Tipo do evento disparado — veja lista abaixo.
`entityId`	uuid	ID interno da entidade relacionada ao evento (a operação de crédito, o documento, o resultado de KYC ou a conta escrow, dependendo do evento).
`occurredAt`	datetime	Timestamp UTC (ISO 8601) do momento em que o evento ocorreu.
`data`	object	Dados completos da entidade. Para eventos de operação de crédito, tem a mesma estrutura da resposta de `GET /credit-operations/{externalContractId}`.

Verificando a autenticidade

Toda requisição de webhook chega com o header:

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

A assinatura tem o formato sha256=<hex>, onde <hex> é o HMAC-SHA256 do corpo bruto (raw body) da requisição, calculado com o secret de webhook fornecido no cadastro do parceiro. Antes de processar qualquer payload, recalcule o HMAC do corpo recebido com o seu secret, prefixe com sha256= e compare com o valor do header — descarte a requisição se não bater.

Lista de eventos

Evento	Categoria	Descrição
`CREDIT_OPERATION_CREATED`	Operação de crédito	Operação criada com sucesso (status `RECEIVED`).
`CREDIT_OPERATION_STATUS_CHANGED`	Operação de crédito	Qualquer mudança de status da operação.
`CCB_GENERATED`	CCB	CCB gerada com sucesso.
`CCB_GENERATION_FAILED`	CCB	Falha ao gerar a CCB.
`CCB_SIGNING_REQUESTED`	CCB	Assinatura eletrônica solicitada ao tomador.
`CCB_SIGNED`	CCB	CCB assinada pelo tomador.
`DISBURSEMENT_REQUESTED`	Desembolso	Desembolso solicitado à plataforma de crédito.
`DISBURSEMENT_COMPLETED`	Desembolso	Valor desembolsado com sucesso.
`DISBURSEMENT_FAILED`	Desembolso	Falha ao desembolsar.
`KYC_REQUESTED`	KYC	Resultado da análise de KYC disponível.
`ESCROW_ACCOUNT_CREATED`	Conta Escrow	Conta escrow aberta com sucesso 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.