Catálogo de Eventos de Webhook

Esta página lista todos os eventos que você pode passar em subscribedEvents ao registrar um endpoint de webhook. 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 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:

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

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.

Eventos de transferência

Disparados à medida que uma transferência 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:

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

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.

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.

Onboarding

Transferências

Automação

Webhooks

Dados de referência

Operacional

Catálogo de Eventos de Webhook

Wildcards

Eventos de cliente

Eventos de transferência

​Wildcards

​Eventos de cliente

​Eventos de transferência

Wildcards

Eventos de cliente

Eventos de transferência