Skip to navigation

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

curl -X POST "https://client.api.corpx.com/v1/webhooks" \
-H "Authorization: Bearer $TOKEN" \
-H "X-Tenant-Id: $TENANT_ID" \
-H "Content-Type: application/json" \
-H "X-Request-Timestamp: $TS" \
-H "X-Content-SHA256: $SHA" \
-H "X-Request-Signature: $SIG" \
-d '{
"url": "https://seu-dominio.com/webhooks/conta",
"accountId": "'"$ACCOUNT_ID"'",
"authType": "HMAC",
"secret": "'"$WEBHOOK_SECRET"'",
"eventTypes": [
"pix.in.completed",
"pix.out.completed",
"pix.out.failed",
"qrcode.paid"
]
}'

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

EventoQuando
pix.in.completedPIX creditado
qrcode.paidQR seu foi pago (sai junto com pix.in.completed)
pix.out.completed / failed / timeoutPIX que você enviou
pix.refund.completedDevolução que você pediu
ted.out.confirmed / failedTED que você enviou
ted.in.receivedTED creditado
boleto.paidBoleto liquidado
transfer.internal.in / outTransferência interna
identity.verification.completedVerificação de identidade standalone terminou

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.

{
"id": "idv-idv_01J8Y7C8D9E0F1G2H3J4-completed",
"type": "identity.verification.completed",
"occurredAt": "2026-09-24T14:08:12.000Z",
"schemaVersion": "1.0",
"environment": "production",
"tenantId": "tenant-acme",
"data": {
"verificationId": "idv_01J8Y7C8D9E0F1G2H3J4",
"status": "APPROVED",
"purpose": "second_factor_reset",
"referenceId": "reset_01J8Y6N7M8P9Q0R1S2T3",
"document": "12345678909",
"failureReason": null,
"completedAt": "2026-09-24T14:08:12.000Z",
"consumableUntil": "2026-09-24T14:18:12.000Z",
"method": "facetec_sdk",
"referenceMatch": "dracma",
"checks": {
"liveness": "passed",
"faceMatch": { "result": "passed", "reference": "dracma" }
}
}
}

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.

const crypto = require('node:crypto');
function verifySignature(secret, rawBody, signatureHeader) {
const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('base64');
return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader || '', 'utf8'));
}
// Express: o body precisa ser Buffer, não objeto parseado.
app.post('/webhooks/conta', express.raw({ type: 'application/json' }), (req, res) => {
if (!verifySignature(process.env.WEBHOOK_SECRET, req.body, req.headers['x-signature'])) {
return res.status(403).send('invalid signature');
}
const event = JSON.parse(req.body);
// processe e responda 2xx rápido
res.sendStatus(200);
});

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. Sem fromDate, ú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
  • accountId na criação
  • HMAC conferido com o corpo bruto
  • 2xx rápido; processamento assíncrono
  • Idempotência no seu lado: o mesmo eventId pode chegar de novo