Webhooks da conta
A API avisa o seu servidor quando o dinheiro entra, sai ou falha. Você
cria a assinatura com o accountId da sua conta; omitir devolve
422 account_id_required. Não existe assinatura “de todas as contas”
com esta credencial — isso seria ler o movimento de outra pessoa.
Host: https://client.api.corpx.com. O envelope e o catálogo completo
de tipos estão em Webhooks (referência). Aqui está o
recorte que importa no primeiro dia.
Criar a assinatura
accountId não se edita depois. Trocar de URL ou de eventos: PUT /v1/webhooks/{subscriptionId}. Trocar de conta: crie outra assinatura.
authType: HMAC é o recomendado. O segredo nunca volta nas
respostas (hmacSecretSet: true|false). Omitir secret no PUT
mantém a chave; enviar um valor novo rotaciona; authType: "NONE"
apaga a chave.
Lista de tipos: GET /v1/webhooks/events.
Eventos úteis no primeiro dia
O catálogo tem dezenas de outros (MED, tarifas, accreditation). Só assine o que você vai tratar.
identity.verification.completed
A master M2M recebe este evento quando uma verificação standalone termina como
APPROVED, FAILED ou EXPIRED. Não há evento para PENDING. A verificação
é do tenant, não de uma conta, por isso o envelope não inclui accountId.
Assine o evento com a master em uma assinatura do tenant, sem accountId;
assinaturas filtradas por conta não recebem eventos sem conta.
Toda entrega traz X-Signature; valide os bytes brutos e deduplique por id.
Em FAILED ou EXPIRED, failureReason informa o motivo e
consumableUntil é omitido. method diz se a jornada foi por link ou pelo
facetec_sdk; neste caso referenceMatch e checks mostram o que a
aprovação prova (checks.faceMatch.result = not_performed quando
referenceMatch é none: só vida, não identidade). O evento não consome a aprovação: a master ainda
precisa chamar POST /v1/identity-verifications/{verificationId}/consume com
o mesmo purpose e referenceId. Veja
Verificação de identidade.
Validar o HMAC
Com authType: HMAC, cada entrega traz X-Signature:
base64(HMAC_SHA256(secret, corpo_bruto)) — Base64 padrão, com padding.
Use os bytes brutos — re-serializar o JSON muda a ordem dos campos
e invalida a assinatura.
Responda 2xx quando receber o envelope. Trabalho pesado fica na fila. 4xx/5xx disparam nova tentativa.
Entregas e reenvio
GET /v1/webhooks/{subscriptionId}/deliveries— tentativas, mais recentes primeiro. SemfromDate, últimos 7 dias.GET /v1/webhooks/{subscriptionId}/deliveries/{deliveryId}— envelope enviado, quando persistido.POST .../deliveries/{deliveryId}/retry— reentrega só nesta assinatura.
Pedido de aumento de limite
limit_request.created chega quando o pedido abre. limit_request.updated
chega quando o pedido é aprovado, recusado ou cancelado.
data.actingDocument diz quem pediu. data.approvedLimitBrl é o teto
aplicado e pode ser menor que o pedido. data.effectiveAt null significa
que o teto novo já vale. Em um pedido com várias operações, data.bundleId
identifica o lote e data.items traz cada operação. account.limits.updated chega quando um teto
muda de verdade; na aprovação ele convive com limit_request.updated, sem
ordem. Deduplique pelo id do envelope. O shape está no
guia de webhooks BaaS.
Checklist
- HTTPS no seu endpoint
-
accountIdna criação - HMAC conferido com o corpo bruto
- 2xx rápido; processamento assíncrono
- Idempotência no seu lado: o mesmo
eventIdpode chegar de novo