Webhook de Status da Proposta – Novo

---

1. Visão geral #

O webhook-proposal-status é um mecanismo de notificação assíncrona responsável por enviar, via HTTP POST, atualizações de status da proposta de
Empréstimo Consignado (INSS) para um endpoint configurado por cliente (ClientId).

2. Contexto na esteira de aquisição #

O webhook de status é acionado ao longo de toda a esteira de aquisição, sempre que ocorre uma alteração no status da proposta. A cada evento, é retornado o status da etapa executada, permitindo o acompanhamento contínuo da evolução da operação. 

O mecanismo contempla todas as etapas do processo, incluindo Validação de Crivo, Averbação, Integração Documental, Anuência, Desembolso e Encarteiramento.

Além disso, é possível configurar webhooks distintos para cada status ou etapa do fluxo, permitindo que diferentes sistemas consumidores sejam notificados de forma específica conforme a evolução da proposta.

3. Contrato do webhook enviado ao cliente (saída HTTP) #

Para cada evento consumido, o Worker envia um HTTP POST para o endpoint configurado.

4. Método e headers #

Item	Valor
Método	POST
Content-Type	application/json
Timeout	5 segundos
Headers de autenticação	Dependem de webhook_config.auth_type

5. Autenticação e autorização (envio do webhook) #

O Worker adiciona o header conforme o campo auth_type.

auth_type (webhook_config)	Comportamento	Exemplo de header enviado
BEARER	Adiciona Authorization: Bearer {auth_config}	Authorization: Bearer eyJ…
API_KEY	Adiciona x-api-key: {auth_config}	x-api-key: 7f9c…

6. Respostas esperadas e tratamento de erros #

O endpoint do cliente deve retornar:

• HTTP 2xx: entrega considerada bem-sucedida (delivery_status = SENT).
• HTTP 4xx: falha definitiva (delivery_status = FAILED) e evento segue para retentativa/erro conforme RetryAmount.
• HTTP 5xx: falha do servidor do cliente (delivery_status = FAILED) e evento segue para retentativa/erro conforme RetryAmount.
• Timeout/Exceção HTTP: falha técnica (delivery_status = FAILED) e evento segue para retentativa/erro conforme RetryAmount.

7. Webhook por Evento #

7.1. Crivo #

Sucesso

{
 "webhook_type": "worker_credit.eligibility",
 "success": true,
 "data": {
   "id": "<<uuid da proposta>>"
 }
}

Falha

{
 "webhook_type": "worker_credit.eligibility",
 "success": false,
 "data": {
   "id": "<<uuid da proposta>>",
   "message": "Descrição da falha"
 }
}

7.2. Averbação #

Sucesso

{
 "webhook_type": "worker_credit.endorsement",
 "success": true,
 "data": {
   "id": "<<uuid da proposta>>",
   "raw_dataprev_data": {}
 }
}

Teimosinha:

{
 "webhook_type": "worker_credit.endorsement",
 "success": false,
 "data": {
   "id": "<<uuid da proposta>>",
   "code": 422,
   "message": "[Código de retorno Dataprev] - [Descrição retorno Dataprev] - RETRY"
   "raw_dataprev_data": {}
 }
}

Falha

{
 "webhook_type": "worker_credit.endorsement",
 "success": false,
 "data": {
   "id": "<<uuid da proposta>>",
   "code": "OV",
   "message": "Descrição da falha",
   "raw_dataprev_data": {
     "message": "Json do retorno cru da dataprev"
   }
 }
}

7.3. Integração Documental #

Sucesso

{
 "webhook_type": "worker_credit.document_integration",
 "success": true,
 "data": {
 "id": "<<uuid da proposta>>",
   "raw_documental_data": {}
 }
}

Falha

{
 "webhook_type": "worker_credit.document_integration",
 "success": false,
 "data": {
   "id": "<<uuid da proposta>>",
   "code": "OV",
   "message": "Descrição da falha",
   "raw_documental_data": {
     "message": "Json do retorno cru da integração documental"
   }
 }
}

7.4. Confirmação de Anuência #

Sucesso

{ 
  "webhook_type": "worker_credit.consent", 
  "success": true,
  "data": {
    "id": "<<uuid da proposta>>",
    "raw_dataprev_data": {}
  }
}

Falha

{ 
 "webhook_type": "worker_credit. consent ",
 "success": false,
 "data": {
   "id": "<<uuid da proposta>>",
   "code": "OV",
   "message": "Descrição da falha",
   "raw_dataprev_data": {
     "message": "Json do retorno cru da dataprev"
   }
 }
}

7.5. Aprovação de Pagamento (Paradinha Corban) #

Sucesso

{
 "webhook_type": "worker_credit.awaiting_corban_action",
 "success": true,
 "data": {
   "id": "<<uuid da proposta>>",
   "raw_corban_data": {
      "message": "{\"eventId\":\"b9e1a4f2-3d67-4c90-8e25-1a45b7c2d3e5\",\"numeroContratoOriginal\":\"983354331\",\"numeroContratoInterno\":\"2026080600021\",\"cpf\":\"12345678909\",\"nomeCliente\":\"Maria Aparecida da Silva\",\"bancoOriginador\":\"Banco Teste.\",\"saldoPortado\":18450.75,\"quantidadeParcelasPortada\":84,\"quantidadeParcelasVencidas\":3,\"dataPrimeiroVencimento\":\"2026-08-05\",\"dataUltimoVencimento\":\"2033-07-05\"}"
  }
 }
}

Falha

{
 "webhook_type": "worker_credit.awaiting_corban_action",
 "success": false,
 "data": {
   "id": "<<uuid da proposta>>",
   "code": "400",
   "message": "Descrição da falha"
 }
}

7.6. Desembolso #

Sucesso

{
 "webhook_type": "worker_credit.disbursement",
 "success": true,
 "data": {
   "id": "<<uuid da proposta>>",
   "payment_datetime": "2025-05-02T10:10:10-03:00"
 }
}

Falha

{
 "webhook_type": "worker_credit.disbursement",
 "success": false,
 "data": {
   "id": "<<uuid da proposta>>",
   "code": "500",
   "message": "Descrição da falha"
 }
}

7.7. Encarteiramento #

Sucesso

{
 "webhook_type": "worker_credit.portfolio",
 "success": true,
 "data": {
   "id": "<<uuid da proposta>>"
 }
}

Falha

{
 "webhook_type": "worker_credit.portfolio",
 "success": false,
 "data": {
   "id": "<<uuid da proposta>>",
   "code": "500",
   "message": "Descrição da falha"
 }
}

8. Observações Importantes #

• Os exemplos acima representam payloads reais utilizados atualmente.
• O campo success = false indica falha de negócio/processo, não falha no envio do webhook.
• O campo id retornado corresponde ao mesmo identificador enviado na criação da proposta, no campo contract.id da requisição de inclusão de proposta.