> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spherepay.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Catálogo de Eventos de Webhook

> Todos os assuntos de evento de webhook que você pode assinar — eventos de cliente e de transferência, com seus gatilhos e exemplos de payload.

Esta página lista todos os eventos que você pode passar em `subscribedEvents` ao [registrar um endpoint de webhook](/pt-BR/concepts/webhooks/managing-endpoints). Os nomes dos eventos seguem a convenção `{resource}.{subject}`. Os eventos são disparados em transições do status publicamente observável do recurso — estados exclusivamente internos nunca produzem eventos de webhook.

## Wildcards

Além de nomes de evento individuais, `subscribedEvents` aceita:

| Valor        | Assina                            |
| ------------ | --------------------------------- |
| `*`          | Todos os eventos                  |
| `customer.*` | Todos os eventos de cliente       |
| `transfer.*` | Todos os eventos de transferência |

## Eventos de cliente

Disparados à medida que o [perfil de verificação](/pt-BR/concepts/onboarding/verification-profile) de um cliente avança pelo seu ciclo de vida de status. Um evento é disparado por perfil de verificação por transição — um cliente com múltiplos perfis produz um fluxo de eventos independente por perfil.

| Evento              | Gatilho                                                                                                                                                                                      |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `customer.created`  | `POST /v2/customer` é bem-sucedido. `previousStatus` é `null`, `status` é `incomplete` e `verificationProfile` é `null` (o evento marca a criação da entidade, não uma transição de perfil). |
| `customer.pending`  | Todos os itens de critérios `required` são resolvidos para um perfil de verificação.                                                                                                         |
| `customer.approved` | O SpherePay conclui a análise e aprova o perfil de verificação.                                                                                                                              |
| `customer.rejected` | O SpherePay conclui a análise e rejeita o perfil de verificação.                                                                                                                             |

Exemplo — `customer.approved`:

```json theme={"dark"}
{
  "id": "event_01HXP9ZK7Q4ABC123",
  "type": "customer.approved",
  "apiVersion": "v2",
  "originalCreateDate": "2026-08-07T14:00:00.123456Z",
  "livemode": true,
  "sequence": 3,
  "data": {
    "id": "customer_f31121c389624d3697cbf3ea8830b7a4",
    "type": "customer",
    "applicationId": "application_1324354657",
    "verificationProfile": "kyc_profile_a",
    "previousStatus": "pending",
    "previousStatusAt": "2026-08-06T10:15:30.000Z",
    "status": "approved",
    "statusAt": "2026-08-07T14:00:00.000Z",
    "cause": null
  }
}
```

<Note>
  O campo `cause` é reservado para um motivo de rejeição legível por máquina. Atualmente ele é sempre `null`, inclusive em `customer.rejected` — motivos de rejeição estruturados serão lançados em uma próxima versão.
</Note>

## Eventos de transferência

Disparados à medida que uma [transferência](/pt-BR/concepts/transfers/lifecycle) avança pelo seu ciclo de vida de status. Webhooks agora são a forma recomendada de acompanhar o progresso de transferências.

| Evento                              | Gatilho                                                                                                                                                                                     |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `transfer.created`                  | `POST /v2/transfer` é bem-sucedido. `previousStatus` é `null`; `status` é o estado inicial (tipicamente `pendingFunding`).                                                                  |
| `transfer.pendingFunding`           | A transferência retornou para `pendingFunding` — por exemplo, após sair de `pendingReview`. O estado `pendingFunding` inicial é coberto por `transfer.created`, não por um evento separado. |
| `transfer.pendingReview`            | A transferência entrou em `pendingReview` — o pagamento pode exigir análise adicional de compliance.                                                                                        |
| `transfer.fundsReceived`            | O SpherePay detectou fundos do cliente.                                                                                                                                                     |
| `transfer.processing`               | O processamento começou.                                                                                                                                                                    |
| `transfer.succeeded`                | Sucesso terminal — fundos entregues ao destino.                                                                                                                                             |
| `transfer.returned`                 | O banco de destino devolveu a transferência.                                                                                                                                                |
| `transfer.pendingRefundInformation` | O SpherePay precisa de informações do cliente para concluir um reembolso.                                                                                                                   |
| `transfer.refunded`                 | O reembolso foi entregue ao cliente.                                                                                                                                                        |
| `transfer.failed`                   | Falha terminal.                                                                                                                                                                             |
| `transfer.canceled`                 | O cliente cancelou antes do financiamento.                                                                                                                                                  |
| `transfer.expired`                  | A transferência expirou antes do financiamento.                                                                                                                                             |
| `transfer.failedPrecondition`       | As informações fornecidas pelo cliente falharam em uma verificação de pré-condição.                                                                                                         |
| `transfer.unexpectedError`          | Ocorreu um erro inesperado durante o processamento.                                                                                                                                         |

Exemplo — `transfer.succeeded`:

```json theme={"dark"}
{
  "id": "event_01HXPA3M9R7DEF456",
  "type": "transfer.succeeded",
  "apiVersion": "v2",
  "originalCreateDate": "2026-08-07T14:05:30.000Z",
  "livemode": true,
  "sequence": 5,
  "data": {
    "id": "payout_d243ab2b1de4447d8a046d87fefe58cf",
    "type": "transfer",
    "applicationId": "application_1324354657",
    "customerId": "customer_f31121c389624d3697cbf3ea8830b7a4",
    "transferType": "oneTimeTransfer",
    "previousStatus": "processing",
    "previousStatusAt": "2026-08-07T14:02:15.000Z",
    "status": "succeeded",
    "statusAt": "2026-08-07T14:05:30.000Z",
    "cause": null
  }
}
```

<Note>
  Os nomes de eventos de transferência usam o nome público do recurso na API (`transfer.*`), enquanto `data.id` usa o prefixo `payout_` — correspondendo aos IDs retornados pela API `/v2/transfer` hoje. `transferType` é `staticTransfer` para on-ramper accounts e offloader wallets, e `oneTimeTransfer` nos demais casos. O status depreciado `undeliverable` não produz eventos.
</Note>

<Note>
  O campo `cause` é reservado para um motivo de falha legível por máquina em eventos de falha terminal (`transfer.failed`, `transfer.returned`, `transfer.expired`, `transfer.canceled`, `transfer.failedPrecondition`, `transfer.unexpectedError`). Atualmente ele é sempre `null` — motivos de falha estruturados serão lançados em uma próxima versão.
</Note>