> This page is for Internet banking (beta).

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://en.docs.api.corpx.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://en.docs.api.corpx.com/_mcp/server.

# 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)](/baas/guias/conta/webhooks). This page is the
first-day cut.

## Create the subscription

```bash
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

| Event                                      | When                                             |
| ------------------------------------------ | ------------------------------------------------ |
| `pix.in.completed`                         | PIX credited                                     |
| `qrcode.paid`                              | Your QR was paid (fires with `pix.in.completed`) |
| `pix.out.completed` / `failed` / `timeout` | PIX you sent                                     |
| `pix.refund.completed`                     | Refund you requested                             |
| `ted.out.confirmed` / `failed`             | TED you sent                                     |
| `ted.in.received`                          | TED credited                                     |
| `boleto.paid`                              | Boleto settled                                   |
| `transfer.internal.in` / `out`             | Internal transfer                                |
| `identity.verification.completed`          | Standalone 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.

```json
{
  "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](/ib/guias/apis-adicionais/verificacao-de-identidade).

## 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.

```javascript
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](/baas/guias/conta/webhooks).

## 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