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 - Margem

Endpoint de registro: POST /user/webhook/private-consignment/consult

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

Ao registrar o webhook, a API irá realizar uma request POST para o endpoint informado, para validar se o mesmo está ativo e apto a receber as notificações com o seguinte payload

Payload de requisição:

{
  "type": "webhook.test",
  "timestamp": "2000-01-01T00:00:00Z"
}

Confirmação de registro

após o recebimento do webhook de teste, receberá um novo webhook confirmando o registro da url

{
  "type": "webhook.registered",
  "timestamp": "2000-01-01T00:00:00Z",
  "url": "https://example.com/webhook"
}

Consulta de margem:

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

Sucesso na consulta de margem:

{
  "type": "private.consignment.consult.updated",
  "timestamp": "2025-11-12T16:41:00.412Z",
  "consultId": "8b523e72-bccc-4997-96d0-95f2d299d9d5",
  "status": "SUCCESS",
  "availableMarginValue": "350.00",
  "admissionDateMonthsDifference": 67,
  "simulationLimit": {
    "monthMin": 49,
    "monthMax": 72,
    "installmentsMin": 6,
    "installmentsMax": 24,
    "valueMin": 800,
    "valueMax": 25000
  }
}

Falha na consulta de margem:

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

• WAITING_CONSENT : Aguardando consentimento do cliente

• CONSENT_APPROVED : Consentimento aprovado

• WAITING_CONSULT : Aguardando consulta Dataprev

• WAITING_CREDIT_ANALYSIS : Aguardando Análise de Crédito

• SUCCESS : Sucesso

• FAILED : Falha

• REJECTED : Rejeitada na Análise de Crédito

• availableMarginValue: valor da margem consignável disponível para o cliente

• admissionDateMonthsDifference: diferença em meses entre a data atual e a data de admissão do cliente

• simulationLimit: informações sobre os limites de simulação, contendo:

  • monthMin: número mínimo de meses da faixa na qual o cliente se enquadra

  • monthMax: número máximo de meses da faixa na qual o cliente se enquadra

  • installmentsMin: quantidade mínima de parcelas

  • installmentsMax: quantidade máxima de parcelas

  • valueMin: valor mínimo de operação

  • valueMax: valor máximo de operação
    

Registro de Webhook - Propostas

Configurando o webhook de operação, o usuário receberá notificações sempre que houver uma atualização no status de uma operação de consignado privado ou quando uma nova operação for criada. O payload enviado será o seguinte:

Endpoint de registro:
POST /user/webhook/private-consignment/operation

Payload de requisição:

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

{
  "type": "private.consignment.operation.created",
  "timestamp": "2000-01-01T00:00:00Z",
  "operationId": "123e4567-e89b-12d3-a456-426614174000",
  "status": "generating_ccb"
}

• type: tipo do evento, podendo ser:

  • private.consignment.operation.created: operação criada

  • private.consignment.operation.updated: operação atualizada

• timestamp: data e hora do envio do webhook

• operationId: identificador único da operação

• status: status atual da operação, podendo ser:

  • generating_ccb

  • formalization

  • analysis

  • manual_analysis

  • awaiting_call

  • processing

  • paid

  • canceled

  • awaiting_cancel

  • pending

  • refunded

  • rejected

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.