> ## Documentation Index
> Fetch the complete documentation index at: https://developers.portao3.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Receive webhooks

> Understand the notification envelope and the events that drive every async flow

Most flows in these guides finish asynchronously — a PIX is paid, a card is charged, a recurring cycle settles. Portão 3 tells you about these by **webhook**. Your account manager registers the HTTPS endpoint that receives them; deliveries are sent over HTTPS to that pre-registered URL.

## The notification envelope

Every webhook shares the same envelope. The `event` tells you what happened; the `payload` is the affected resource.

```json theme={null}
{
  "notificationId": "03d55ca0-b64d-4484-a8e3-9b38528e4818",
  "source": "WALLET",
  "event": "PIX_BILLING_PAID",
  "payload": {
    "_id": "68823710b8a3dbd2b90ff8d5",
    "status": "PAID"
  }
}
```

| Field            | Meaning                                                                |
| ---------------- | ---------------------------------------------------------------------- |
| `notificationId` | Unique per delivery. Use it to deduplicate — see below.                |
| `source`         | The originating domain. Banking events use `WALLET`.                   |
| `event`          | The event name (see the catalog below).                                |
| `payload`        | The resource the event is about, in the same shape the API returns it. |

<Warning>
  Webhooks can be delivered more than once. Treat `notificationId` as an idempotency key: record the ones you've processed and ignore repeats. Always respond `2xx` quickly and do your processing asynchronously.
</Warning>

## Event catalog

### Payments and charges

| Event                                                                                            | Fires when                                                                  | Guide                                                                              |
| ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `PIX_BILLING_PAID`                                                                               | A PIX charge (QR Code) is paid.                                             | [Charge with PIX](/guides/collect-pix)                                             |
| `PIX_BILLING_AUTOMATIC_CREATED` · `INITIATED` · `SCHEDULED` · `EXPIRED` · `CANCELED`             | The recurring authorization changes state.                                  | [Pix Automático](/guides/pix-automatico#step-2-follow-the-authorization-lifecycle) |
| `PIX_BILLING_AUTOMATIC_SCHEDULE_PENDING_SCHEDULE` · `SCHEDULED` · `PAID` · `FAILED` · `CANCELED` | An individual recurring cycle changes state.                                | [Pix Automático](/guides/pix-automatico#step-3-follow-each-cycle)                  |
| `BOLETO_BILLING_UPDATED`                                                                         | A boleto charge changes state (for example, to `CREATED` with its barcode). | [Pix Automático](/guides/pix-automatico#fall-back-to-boleto-on-repeated-failure)   |

### Cards and wallets

| Event                                           | Fires when                                               | Guide                                                                              |
| ----------------------------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `WALLET_CREATED`                                | A wallet is created.                                     | This guide                                                                         |
| `WALLET_UPDATED`                                | A wallet changes — including its `platformCustomFields`. | This guide                                                                         |
| `WALLET_CARD_CREATED`                           | A card is created on a wallet.                           | [Manage cards](/guides/manage-cards#card-webhooks)                                 |
| `CARD_TRANSACTION` · `CARD_TRANSACTION_REFUSED` | A card is charged, or a charge is refused.               | [Manage cards](/guides/manage-cards#card-webhooks)                                 |
| `TRANSACTION_CUSTOM_FIELDS_UPDATED`             | Custom fields on a transaction change.                   | This guide                                                                         |
| `CARDLESS_PAYMENT_ACTIVATION_CODE_EVENT`        | A card needs a device-wallet verification code.          | [Manage cards](/guides/manage-cards#a-card-needs-a-verification-code-tokenization) |

## Example: provisioning driven by webhooks

A common pattern is to let users self-onboard in the Portão 3 app and have your system react to webhooks rather than calling the API yourself. For example, when a user is invited and links a card, you receive:

```mermaid theme={null}
sequenceDiagram
  participant User
  participant P3 as Portão 3
  participant You
  User->>P3: Accepts invite, links a card in the app
  P3->>You: Webhook WALLET_CREATED
  P3->>You: Webhook WALLET_CARD_CREATED
  Note over You,P3: Later, you enrich the wallet/transaction
  You->>P3: Set custom fields (e.g. the user's CPF)
  P3->>You: Webhook WALLET_UPDATED / TRANSACTION_CUSTOM_FIELDS_UPDATED
```

Custom fields are carried as `platformCustomFields` (on a wallet) or `customFields` (on a transaction), each an array of `{ label, identifier, values, type }`. Use them to attach your own identifiers — a driver's CPF, a mileage reading, an invoice file — and reconcile them when the matching `*_UPDATED` webhook arrives.

<Warning>
  Webhook payloads and custom fields can carry personal data (names, CPF/CNPJ, emails, addresses). Store only what you need, keep it out of plaintext logs, and follow your own retention and minimization obligations under the LGPD.
</Warning>

## Looking up an organization

To resolve an organization's registration details (legal name, document, address) from its `realmId` and `organizationId` — handy when reconciling webhook payloads — use the Identity organization endpoint:

```bash theme={null}
curl 'https://api.identity.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}' \
  -H 'Authorization: Bearer <accessToken>'
```

Reference: [`GET /realms/{realmId}/organizations/{organizationId}`](/api-reference/identity/organizations/realms-organizations-2)

## Next steps

<CardGroup cols={2}>
  <Card title="Charge with PIX" icon="qrcode" href="/guides/collect-pix">
    The simplest webhook-driven flow to test against.
  </Card>

  <Card title="Recurring billing with Pix Automático" icon="repeat" href="/guides/pix-automatico">
    The flow with the richest event lifecycle.
  </Card>
</CardGroup>