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.
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: enviado
no header
X-Hubcred-Tokene usado para calcular a assinaturaX-Hubcred-Signature(HMAC-SHA256 do corpo).
Segurança
Todo webhook chega com os headers abaixo. Valide sempre a autenticidade, peloX-Hubcred-Token e, de preferência, pela assinatura X-Hubcred-Signature.
Validando a assinatura (recomendado)
Além de comparar oX-Hubcred-Token, você pode validar a assinatura
X-Hubcred-Signature: recompute o HMAC-SHA256 do corpo bruto da requisição
usando o seu secret como chave e compare com o valor recebido. Como a
assinatura cobre o payload inteiro, ela também detecta qualquer adulteração no
caminho, uma verificação mais forte que só conferir o token.
Compatibilidade: o
X-Hubcred-Token continua sendo enviado, validar a
assinatura é opcional e pode ser adotado no seu ritmo, sem quebrar integrações
existentes.Resposta esperada
Responda rápido com qualquer código2xx (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
Campos
string (UUID)
Identificador único do evento. Estável entre reenvios, use para deduplicar.
string
Sempre
operation.status_changed nesta versão.string (ISO 8601)
Data/hora em que o status mudou.
string
Código público da operação (o mesmo usado na API de integração).
number
Código do produto da operação (ver tabela de produtos).
number
Status anterior (ver tabela de status).
number
Status novo.
string
Descrição legível do
newStatus em PT-BR.object
Snapshot da operação no momento do evento.
Compatibilidade: podemos adicionar novos campos no futuro. Ignore
campos desconhecidos e não dependa da ordem dos campos.
Tabela de status
Tabela de produtos
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).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
1
Valide o token
Confira o
X-Hubcred-Token em toda requisição e rejeite (401) se não bater.2
Confira a assinatura (recomendado)
Recompute o HMAC-SHA256 do corpo bruto e compare com o
X-Hubcred-Signature.3
Responda 2xx rápido
Confirme o recebimento e processe de forma assíncrona no seu lado.
4
Deduplique por eventId
Pode haver reenvio; ignore eventos já processados.
5
Tolere o desconhecido
Aceite campos e status novos sem quebrar, o contrato evolui de forma aditiva.
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.