Guide

Webhooks

O sistema realiza uma validação ativa das URLs registradas para recebimento de webhooks, garantindo que estejam operacionais. Essa validação é feita por meio de uma requisição HTTP POST ao endpoint correspondente.

Registro de Webhook - Saldo

Endpoint de registro:
POST /user/webhook/balance

Payload de requisição:

{
  "url": "https://urlwebhook.com"
}

Após o registro bem-sucedido da URL, o sistema enviará notificações relacionadas ao status de consulta de saldo no seguinte formato:

Exemplo de Payloads Recebidos:

Falha na consulta de saldo:

{
  "type": "balance.status.received.fail",
  "documentNumber": "00000000002",
  "provider": "bms",
  "errorMessage": "Não foi possível consultar o saldo no momento! - Instituição Fiduciária não possui autorização do Trabalhador para Operação Fiduciária.",
  "timestamp": "2025-01-30T13:06:38.656Z"
}

Sucesso na consulta de saldo:

{
  "type": "balance.status.received.success",
  "documentNumber": "00000000001",
  "provider": "bms",
  "balance": "585.73",
  "timestamp": "2025-01-30T13:29:15.183Z"
}

Registro de Webhook - Propostas

Endpoint de registro:
POST /user/webhook/proposal

Payload de requisição:

{
  "url": "https://urlwebhook.com"
}
Exemplo de Payload Recebido:
{
  "type": "proposal.status.update",
  "timestamp": "2025-01-30T12:37:54.612Z",
  "proposalId": "8d51c218-3ce4-48c6-8ae3-1185a832a2d9",
  "proposalNumber": "123123123/ABC",
  "status": "canceled"
}

Observações

  • O sistema exige que a URL informada esteja acessível e responda adequadamente no momento do registro.

  • As notificações são enviadas via HTTP POST, e espera-se que o endpoint da aplicação cliente retorne status HTTP 2xx para confirmação de recebimento.