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
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
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.
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.
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. WithoutfromDate, 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
-
accountIdat creation - HMAC checked against the raw body
- Fast 2xx; async processing
- Idempotency on your side: the same
eventIdmay arrive again