Catálogo de Eventos de Webhook

Esta página lista cada evento que puedes pasar en subscribedEvents al registrar un endpoint de webhook. 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 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:

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

Eventos de transferencia

Se disparan a medida que una transferencia 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:

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

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.

Incorporación

Transferencias

Automatización

Webhooks

Datos de referencia

Operacional

Catálogo de Eventos de Webhook

Comodines

Eventos de cliente

Eventos de transferencia

​Comodines

​Eventos de cliente

​Eventos de transferencia

Comodines

Eventos de cliente

Eventos de transferencia