Skip to navigation

Account webhooks

The API tells your server when money comes in, goes out or fails. You create the subscription with your account’s accountId; omitting it returns 422 account_id_required. There is no “every account” subscription with this credential — that would read someone else’s movement.

Host: https://client.api.corpx.com. The envelope and the full event catalogue are in Webhooks (reference). This page is the first-day cut.

Create the subscription

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://your-domain.com/webhooks/account",
"accountId": "'"$ACCOUNT_ID"'",
"authType": "HMAC",
"secret": "'"$WEBHOOK_SECRET"'",
"eventTypes": [
"pix.in.completed",
"pix.out.completed",
"pix.out.failed",
"qrcode.paid"
]
}'

accountId is not editable afterwards. Change URL or events: PUT /v1/webhooks/{subscriptionId}. Change account: create another subscription.

authType: HMAC is recommended. The secret never comes back in responses (hmacSecretSet: true|false). Omitting secret on PUT keeps the key; sending a new value rotates it; authType: "NONE" deletes the key.

Event types: GET /v1/webhooks/events.

Useful first-day events

EventWhen
pix.in.completedPIX credited
qrcode.paidYour QR was paid (fires with pix.in.completed)
pix.out.completed / failed / timeoutPIX you sent
pix.refund.completedRefund you requested
ted.out.confirmed / failedTED you sent
ted.in.receivedTED credited
boleto.paidBoleto settled
transfer.internal.in / outInternal transfer
identity.verification.completedStandalone identity verification completed

The catalogue has dozens more (MED, fees, accreditation). Subscribe only to what you will handle.

identity.verification.completed

The master M2M receives this event when a standalone verification ends as APPROVED, FAILED, or EXPIRED. There is no event for PENDING. The verification belongs to the tenant, not a bank account, so the envelope does not include accountId. Subscribe with the master on a tenant-scoped subscription, without accountId; account-filtered subscriptions do not receive events without an account.

{
"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" }
}
}
}

Every delivery includes X-Signature; verify the raw bytes and deduplicate on id. For FAILED or EXPIRED, failureReason carries the reason and consumableUntil is omitted. method tells whether the journey used link or the facetec_sdk; in the latter case referenceMatch and checks show what the approval proves (checks.faceMatch.result = not_performed when referenceMatch is none: liveness only, not identity). The event does not consume an approval: the master must still call POST /v1/identity-verifications/{verificationId}/consume with the same purpose and referenceId. See Identity verification.

Verify HMAC

With authType: HMAC, each delivery has X-Signature: base64(HMAC_SHA256(secret, raw_body)) — standard Base64, with padding. Use the raw bytes — re-serializing JSON changes field order and invalidates the signature.

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: the body must be a Buffer, not a parsed object.
app.post('/webhooks/account', 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);
// handle and reply 2xx quickly
res.sendStatus(200);
});

Reply 2xx when you receive the envelope. Heavy work goes on a queue. 4xx/5xx trigger another attempt.

Deliveries and retry

  • GET /v1/webhooks/{subscriptionId}/deliveries — attempts, newest first. Without fromDate, last 7 days.
  • GET /v1/webhooks/{subscriptionId}/deliveries/{deliveryId} — outbound envelope, when persisted.
  • POST .../deliveries/{deliveryId}/retry — redeliver to this subscription only.

Limit increase

limit_request.created arrives when the request opens. limit_request.updated arrives when the request is approved, refused or cancelled. data.actingDocument is who asked. data.approvedLimitBrl is the ceiling that was applied and may be lower than the request. A null data.effectiveAt means the new ceiling is already in force. For a multi-operation request, data.bundleId identifies the bundle and data.items carries every operation. account.limits.updated arrives when a ceiling actually changes; on approval it sits next to limit_request.updated, with no order. Deduplicate by the envelope id. The shape is in the BaaS webhooks guide.

Checklist

  • HTTPS on your endpoint
  • accountId at creation
  • HMAC checked against the raw body
  • Fast 2xx; async processing
  • Idempotency on your side: the same eventId may arrive again