> 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://docs.api.corpx.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.api.corpx.com/_mcp/server.

# 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)](/baas/guias/conta/webhooks). Aqui está o
recorte que importa no primeiro dia.

## Criar a assinatura

```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://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

| Evento                                     | Quando                                             |
| ------------------------------------------ | -------------------------------------------------- |
| `pix.in.completed`                         | PIX creditado                                      |
| `qrcode.paid`                              | QR seu foi pago (sai junto com `pix.in.completed`) |
| `pix.out.completed` / `failed` / `timeout` | PIX que você enviou                                |
| `pix.refund.completed`                     | Devolução que você pediu                           |
| `ted.out.confirmed` / `failed`             | TED que você enviou                                |
| `ted.in.received`                          | TED creditado                                      |
| `boleto.paid`                              | Boleto liquidado                                   |
| `transfer.internal.in` / `out`             | Transferência interna                              |
| `identity.verification.completed`          | Verificaçã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.

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

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](/ib/guias/apis-adicionais/verificacao-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.

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

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