Webhook de mudança de status

A HubCred pode notificar seu sistema automaticamente sempre que o status de uma operação mudar — assim você não precisa ficar consultando (polling) a API. Quando o status muda, enviamos um POST para a URL de callback que você configurou, com um objeto JSON descrevendo o evento.

Como funciona

O evento é operation.status_changed, disparado a cada mudança de status de uma operação sua.
A entrega é assíncrona: você recebe o webhook poucos instantes após a mudança (não no mesmo instante da ação).
A entrega é confiável: se o seu endpoint não responder 2xx, tentamos novamente em intervalos fixos; após esgotar as tentativas, o evento vai para uma fila de dead-letter e pode ser reprocessado.
Ordenação por operação: eventos de uma mesma operação chegam na ordem em que aconteceram; operações diferentes são entregues em paralelo.

Entrega “pelo menos uma vez” (at-least-once). Em cenários raros de falha, um mesmo evento pode ser reenviado. Use o eventId (também no header X-Hubcred-Event-Id) para deduplicar no seu lado.

Configuração

A URL de callback e o secret de assinatura são configurados pela HubCred por loja/integração. Fale com o seu contato HubCred para cadastrar ou rotacionar:

URL de callback — o endpoint HTTPS que receberá os POST.
Secret — chave para você validar que a requisição veio da HubCred (enviada no header X-Hubcred-Token).

Segurança

Todo webhook chega com os headers abaixo. Valide sempre o X-Hubcred-Token.

Header	Descrição
`Content-Type`	`application/json`
`X-Hubcred-Token`	O secret da sua integração. Compare com o secret fornecido pela HubCred e rejeite (401) se não bater.
`X-Hubcred-Event-Id`	Identificador único do evento (igual ao `eventId` do corpo). Use para idempotência.

Nunca processe um webhook cujo X-Hubcred-Token não corresponda ao seu secret.

Resposta esperada

Responda rápido com qualquer código 2xx (ex.: 200 OK) assim que receber e persistir o evento — de preferência antes de processá-lo (processe de forma assíncrona). Qualquer resposta diferente de 2xx, timeout ou erro de rede é tratada como falha e o evento será reenviado.

Exemplo do objeto enviado

Corpo do POST

{
  "eventId": "3f1c8e2a-9b74-4c1e-a0d2-5f6b7c8d9e01",
  "eventType": "operation.status_changed",
  "occurredAt": "2026-07-17T14:32:10.482-03:00",
  "operationCode": "ABC123",
  "product": 10,
  "previousStatus": 3,
  "newStatus": 2,
  "statusDescription": "Aprovado",
  "operation": {
    "code": "ABC123",
    "product": 10,
    "status": 2,
    "partnerStatus": "APPROVED",
    "customerName": "Maria Fulana de Tal",
    "customerRegistryCode": "12345678900",
    "value": 5000.00,
    "finalValue": 5850.00,
    "installments": 12,
    "installmentsValue": 487.50,
    "partnerCode": "BMP-998877",
    "sentDate": "2026-07-15T09:10:00-03:00",
    "approvalDate": "2026-07-17T14:32:10-03:00",
    "paymentDate": null,
    "creationTime": "2026-07-15T09:00:00-03:00",
    "description": "Consignado CLT"
  }
}

Campos

eventId

string (UUID)

Identificador único do evento. Estável entre reenvios — use para deduplicar.

eventType

string

Sempre operation.status_changed nesta versão.

occurredAt

string (ISO 8601)

Data/hora em que o status mudou.

operationCode

string

Código público da operação (o mesmo usado na API de integração).

product

number

Código do produto da operação (ver tabela de produtos).

previousStatus

number

Status anterior (ver tabela de status).

newStatus

number

Status novo.

statusDescription

string

Descrição legível do newStatus em PT-BR.

operation

object

Snapshot da operação no momento do evento.

Show campos de operation

code

string

Código público da operação.

product

number

Código do produto.

status

number

Status atual da operação.

partnerStatus

string

Status reportado pelo parceiro/originador, quando houver.

customerName

string

Nome do cliente.

customerRegistryCode

string

CPF/CNPJ do cliente.

value

number

Valor da operação.

finalValue

number

Valor final da operação.

installments

number

Quantidade de parcelas.

installmentsValue

number

Valor de cada parcela.

partnerCode

string

Código da proposta no parceiro/originador.

sentDate

string (ISO 8601)

Data de envio da proposta.

approvalDate

string (ISO 8601) | null

Data de aprovação, quando houver.

paymentDate

string (ISO 8601) | null

Data de pagamento, quando houver.

creationTime

string (ISO 8601)

Data de criação da operação.

description

string

Descrição adicional da operação.

Compatibilidade: podemos adicionar novos campos no futuro. Ignore campos desconhecidos e não dependa da ordem dos campos.

Tabela de status

Código	Significado
0	Simulação
1	Enviado
2	Aprovado
3	Pendente
4	Processando
5	Recusado
6	Cancelado
7	Erro pagamento
8	Pago
9	Aguardando
10	Perda
11	Finalizado
12	Biometria inconclusiva
13	Erro assinatura
14	Erro operação
15	Dados pendentes
16	Rascunho
17	Mesa de crédito da parceira
80	Pré-aprovado
81	Aguard. pagamento
82	Dados inconsistentes
83	Aguardando NF
84	NF em análise
85	NF aprovada
86	NF recusada
91	Pendente autorização
92	Autorizado
101	Aparelho em ativação
102	Liberado
103	Cedido

Trate status desconhecidos com tolerância: novos códigos podem ser introduzidos. Se receber um código que não conhece, registre e ignore em vez de quebrar o processamento.

Tabela de produtos

Código	Produto
1	FGTS Empréstimo
2	FGTS Loja
3	CDC Saúde
5	Cartão Loja
6	Recompras
7	Operação de Crédito
8	Empréstimo Pessoal
9	CDC Varejo
10	Consignado
11	CDC Agil
12	CDC Hub
13	Capital de Giro
14	CDC Celular
15	EP Celular
16	EP Veículo
17	Operação Estruturada

Status por produto

Cada produto emite um subconjunto dos status. A tabela lista os status que normalmente ocorrem em cada produto; alguns são transversais (ver notas).

Produto	Status possíveis
Consignado (10)	0 · 1 · 2 · 3 · 4 · 5 · 6 · 7 · 8 · 9 · 11 · 12 · 13 · 14 · 91 · 92
FGTS Empréstimo / Loja (1, 2)	1 · 2 · 3 · 4 · 6 · 7 · 8 · 9 · 11 · 14
CDC Saúde (3)	1 · 5 · 6 · 8 · 80 · 81 · 82 · 83 · 84 · 85 · 86
CDC Varejo (9)	1 · 2 · 5 · 6 · 8 · 80 · 81 · 82 · 84 · 85 · 86
Cartão Loja (5)	1 · 2 · 3 · 4 · 5 · 6 · 8 · 80
Recompras (6)	1 · 2 · 3 · 4 · 5 · 6 · 8
Operação de Crédito (7)	2 · 4 · 6 · 8
Empréstimo Pessoal (8)	2 · 3 · 4 · 5 · 6 · 7 · 8 · 11 · 14
CDC Agil (11)	1 · 2 · 4 · 5 · 6
CDC Hub (12)	2 · 4 · 5 · 6 · 9 · 14 · 17
Capital de Giro (13)	2 · 3 · 4 · 6
CDC Celular (14)	2 · 4 · 6 · 9 · 14 · 101
EP Celular (15)	2 · 4 · 6 · 9 · 14 · 101
EP Veículo (16)	2 · 4 · 6 · 9 · 14
Operação Estruturada (17)	4 · 6 · 8 · 11 · 16 · 102 · 103

Status transversais. 12/13 (biometria/assinatura) ocorrem em produtos com assinatura eletrônica; 10 (Perda) por expiração automática; a pré-análise de crédito pode emitir 1, 5, 80, 15, 9 antes da esteira do produto. Os status em negrito são (quase) exclusivos daquele produto: 91/92 = Consignado; 83–86 = CDC (NF); 101 = celular; 16/102/103 = Operação Estruturada; 17 = CDC Hub.

Boas práticas

Valide o token

Confira o X-Hubcred-Token em toda requisição e rejeite (401) se não bater.

Responda 2xx rápido

Confirme o recebimento e processe de forma assíncrona no seu lado.

Deduplique por eventId

Pode haver reenvio; ignore eventos já processados.

Tolere o desconhecido

Aceite campos e status novos sem quebrar — o contrato evolui de forma aditiva.

Use operationCode para casar o evento com a operação no seu sistema; se precisar de mais dados, consulte a operação pela Referência da API.

Introdução

Autenticação

Webhooks

Webhook de mudança de status

Como funciona

Configuração

Segurança

Resposta esperada

Exemplo do objeto enviado

Campos

Tabela de status

Tabela de produtos

Status por produto

Boas práticas

​Como funciona

​Configuração

​Segurança

​Resposta esperada

​Exemplo do objeto enviado

​Campos

​Tabela de status

​Tabela de produtos

​Status por produto

​Boas práticas

Como funciona

Configuração

Segurança

Resposta esperada

Exemplo do objeto enviado

Campos

Tabela de status

Tabela de produtos

Status por produto

Boas práticas