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

> Cada tipo de evento de webhook al que puedes suscribirte — eventos de cliente y de transferencia, con sus desencadenantes y payloads de ejemplo.

Esta página lista cada evento que puedes pasar en `subscribedEvents` al [registrar un endpoint de webhook](/es/concepts/webhooks/managing-endpoints). Los nombres de eventos siguen la convención `{resource}.{subject}`. Los eventos se disparan en las transiciones del estado públicamente observable del recurso — los estados internos nunca producen eventos de webhook.

## Comodines

Además de nombres de eventos individuales, `subscribedEvents` acepta:

| Valor        | Se suscribe a                      |
| ------------ | ---------------------------------- |
| `*`          | Todos los eventos                  |
| `customer.*` | Todos los eventos de cliente       |
| `transfer.*` | Todos los eventos de transferencia |

## Eventos de cliente

Se disparan a medida que el [perfil de verificación](/es/concepts/onboarding/verification-profile) de un cliente avanza por su ciclo de vida de estados. Se dispara un evento por perfil de verificación por transición — un cliente con múltiples perfiles produce un flujo de eventos independiente por perfil.

| Evento              | Desencadenante                                                                                                                                                                                    |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `customer.created`  | `POST /v2/customer` tiene éxito. `previousStatus` es `null`, `status` es `incomplete` y `verificationProfile` es `null` (el evento marca la creación de la entidad, no una transición de perfil). |
| `customer.pending`  | Todos los elementos de criterios `required` se resuelven para un perfil de verificación.                                                                                                          |
| `customer.approved` | SpherePay completa la revisión y aprueba el perfil de verificación.                                                                                                                               |
| `customer.rejected` | SpherePay completa la revisión y rechaza el perfil de verificación.                                                                                                                               |

Ejemplo — `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>
  El campo `cause` está reservado para una razón de rechazo legible por máquina. Actualmente siempre es `null`, incluso en `customer.rejected` — las razones de rechazo estructuradas llegarán en una próxima versión.
</Note>

## Eventos de transferencia

Se disparan a medida que una [transferencia](/es/concepts/transfers/lifecycle) avanza por su ciclo de vida de estados. Los webhooks son ahora la forma recomendada de rastrear el progreso de las transferencias.

| Evento                              | Desencadenante                                                                                                                                                                                      |
| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `transfer.created`                  | `POST /v2/transfer` tiene éxito. `previousStatus` es `null`; `status` es el estado inicial (típicamente `pendingFunding`).                                                                          |
| `transfer.pendingFunding`           | La transferencia regresó a `pendingFunding` — por ejemplo, después de salir de `pendingReview`. El estado `pendingFunding` inicial está cubierto por `transfer.created`, no por un evento separado. |
| `transfer.pendingReview`            | La transferencia entró en `pendingReview` — el pago puede requerir revisión de cumplimiento adicional.                                                                                              |
| `transfer.fundsReceived`            | SpherePay detectó fondos del cliente.                                                                                                                                                               |
| `transfer.processing`               | El procesamiento comenzó.                                                                                                                                                                           |
| `transfer.succeeded`                | Éxito terminal — fondos entregados al destino.                                                                                                                                                      |
| `transfer.returned`                 | El banco de destino devolvió la transferencia.                                                                                                                                                      |
| `transfer.pendingRefundInformation` | SpherePay necesita información del cliente para completar un reembolso.                                                                                                                             |
| `transfer.refunded`                 | El reembolso fue entregado al cliente.                                                                                                                                                              |
| `transfer.failed`                   | Fallo terminal.                                                                                                                                                                                     |
| `transfer.canceled`                 | El cliente canceló antes del fondeo.                                                                                                                                                                |
| `transfer.expired`                  | La transferencia expiró antes del fondeo.                                                                                                                                                           |
| `transfer.failedPrecondition`       | La información proporcionada por el cliente no pasó una verificación de precondición.                                                                                                               |
| `transfer.unexpectedError`          | Ocurrió un error inesperado durante el procesamiento.                                                                                                                                               |

Ejemplo — `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>
  Los nombres de eventos de transferencia usan el nombre público del recurso de la API (`transfer.*`), mientras que `data.id` usa el prefijo `payout_` — coincidiendo con los IDs que devuelve la API `/v2/transfer` hoy. `transferType` es `staticTransfer` para cuentas on-ramper y billeteras offloader, y `oneTimeTransfer` en los demás casos. El estado deprecado `undeliverable` no produce eventos.
</Note>

<Note>
  El campo `cause` está reservado para una razón de fallo legible por máquina en los eventos de fallo terminal (`transfer.failed`, `transfer.returned`, `transfer.expired`, `transfer.canceled`, `transfer.failedPrecondition`, `transfer.unexpectedError`). Actualmente siempre es `null` — las razones de fallo estructuradas llegarán en una próxima versión.
</Note>