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

# Receber webhooks

> Entenda o envelope de notificação e os eventos que impulsionam cada fluxo assíncrono

A maioria dos fluxos destes guias termina de forma assíncrona — um PIX é pago, um cartão é debitado, um ciclo recorrente é liquidado. O Portão 3 avisa você sobre isso por **webhook**. Seu gerente de contas registra o endpoint HTTPS que os recebe; as entregas são enviadas via HTTPS para essa URL previamente registrada.

## O envelope de notificação

Todo webhook compartilha o mesmo envelope. O `event` informa o que aconteceu; o `payload` é o recurso afetado.

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

| Campo            | Significado                                                               |
| ---------------- | ------------------------------------------------------------------------- |
| `notificationId` | Único por entrega. Use-o para deduplicar — veja abaixo.                   |
| `source`         | O domínio de origem. Eventos de Banking usam `WALLET`.                    |
| `event`          | O nome do evento (veja o catálogo abaixo).                                |
| `payload`        | O recurso ao qual o evento se refere, no mesmo formato que a API retorna. |

<Warning>
  Webhooks podem ser entregues mais de uma vez. Trate `notificationId` como uma chave de idempotência: registre os que você já processou e ignore repetições. Sempre responda `2xx` rapidamente e faça o processamento de forma assíncrona.
</Warning>

## Catálogo de eventos

### Pagamentos e cobranças

| Evento                                                                                           | Dispara quando                                                                               | Guia                                                                               |
| ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `PIX_BILLING_PAID`                                                                               | Uma cobrança PIX (QR Code) é paga.                                                           | [Cobrar com PIX](/guides/collect-pix)                                              |
| `PIX_BILLING_AUTOMATIC_CREATED` · `INITIATED` · `SCHEDULED` · `EXPIRED` · `CANCELED`             | A autorização recorrente muda de estado.                                                     | [PIX Automático](/guides/pix-automatico#step-2-follow-the-authorization-lifecycle) |
| `PIX_BILLING_AUTOMATIC_SCHEDULE_PENDING_SCHEDULE` · `SCHEDULED` · `PAID` · `FAILED` · `CANCELED` | Um ciclo recorrente individual muda de estado.                                               | [PIX Automático](/guides/pix-automatico#step-3-follow-each-cycle)                  |
| `BOLETO_BILLING_UPDATED`                                                                         | Uma cobrança por boleto muda de estado (por exemplo, para `CREATED` com o código de barras). | [PIX Automático](/guides/pix-automatico#fall-back-to-boleto-on-repeated-failure)   |

### Cartões e carteiras

| Evento                                          | Dispara quando                                                            | Guia                                                                                    |
| ----------------------------------------------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `WALLET_CREATED`                                | Uma carteira é criada.                                                    | Este guia                                                                               |
| `WALLET_UPDATED`                                | Uma carteira muda — incluindo seus `platformCustomFields`.                | Este guia                                                                               |
| `WALLET_CARD_CREATED`                           | Um cartão é criado em uma carteira.                                       | [Gerenciar cartões](/guides/manage-cards#card-webhooks)                                 |
| `CARD_TRANSACTION` · `CARD_TRANSACTION_REFUSED` | Um cartão é debitado, ou uma cobrança é recusada.                         | [Gerenciar cartões](/guides/manage-cards#card-webhooks)                                 |
| `TRANSACTION_CUSTOM_FIELDS_UPDATED`             | Campos personalizados em uma transação mudam.                             | Este guia                                                                               |
| `CARDLESS_PAYMENT_ACTIVATION_CODE_EVENT`        | Um cartão precisa de um código de verificação de carteira de dispositivo. | [Gerenciar cartões](/guides/manage-cards#a-card-needs-a-verification-code-tokenization) |

## Exemplo: provisionamento guiado por webhooks

Um padrão comum é deixar os usuários fazerem o próprio onboarding no aplicativo Portão 3 e seu sistema reagir a webhooks em vez de chamar a API diretamente. Por exemplo, quando um usuário é convidado e vincula um cartão, você recebe:

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

Os campos personalizados são carregados como `platformCustomFields` (em uma carteira) ou `customFields` (em uma transação), cada um um array de `{ label, identifier, values, type }`. Use-os para anexar seus próprios identificadores — o CPF de um motorista, uma leitura de quilometragem, um arquivo de nota fiscal — e reconciliá-los quando o webhook `*_UPDATED` correspondente chegar.

<Warning>
  Payloads de webhook e campos personalizados podem carregar dados pessoais (nomes, CPF/CNPJ, e-mails, endereços). Armazene apenas o necessário, mantenha-os fora de logs em texto puro e siga suas próprias obrigações de retenção e minimização sob a LGPD.
</Warning>

## Consultar uma organização

Para resolver os dados cadastrais de uma organização (razão social, documento, endereço) a partir de seu `realmId` e `organizationId` — útil ao reconciliar payloads de webhook — use o endpoint de organização do Identity:

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

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

## Próximos passos

<CardGroup cols={2}>
  <Card title="Cobrar com PIX" icon="qrcode" href="/guides/collect-pix">
    O fluxo guiado por webhook mais simples para testar.
  </Card>

  <Card title="Cobrança recorrente com PIX Automático" icon="repeat" href="/guides/pix-automatico">
    O fluxo com o ciclo de vida de eventos mais rico.
  </Card>
</CardGroup>