Explorar Eventos y Reenviar Entregas

Cada evento que SpherePay crea — y cada intento de entregarlo — queda registrado y es consultable. Usa la API de Eventos para auditar lo que sucedió, diagnosticar entregas fallidas y volver a enviar cualquier entrega a tu endpoint. Las vistas del Dashboard para explorar y reenviar eventos llegarán pronto; hoy estos controles viven en la API.

Listar eventos

curl "https://api.spherepay.co/v2/events?type=transfer.*&status=failed&page=1&limit=10" \
  -H "Authorization: Bearer {{api_key}}"

Parámetro	Descripción
`type`	Filtro por tipo de evento — un nombre exacto (`transfer.succeeded`), un comodín de recurso (`transfer.`) o ``.
`status`	Filtra por estado de entrega: `queued`, `delivering`, `delivered` o `failed`.
`webhookEndpointId`	Solo eventos con una entrega al endpoint indicado.
`createdStart` / `createdEnd`	Límites ISO 8601 inclusivos sobre la hora de creación del evento.
`page` / `limit`	Paginación (por defecto `1` / `10`, límite máximo `100`).

Cada elemento de la lista resume el evento y su entrega más reciente:

{
  "data": [
    {
      "id": "event_01HXPA3M9R7DEF456",
      "type": "transfer.succeeded",
      "createdAt": "2026-08-07T14:05:30.123Z",
      "sequence": 5,
      "delivery": {
        "id": "eventDelivery_2351653173",
        "webhookEndpointId": "whk_01HXP9TN3J2ABC",
        "status": "delivered",
        "attemptsUsed": 1,
        "deliveredAt": "2026-08-07T14:05:31.821Z",
        "latestAttempt": {
          "type": "original",
          "success": true,
          "responseCode": 200
        }
      }
    }
  ],
  "page": 1,
  "limit": 10,
  "total": 1,
  "totalPages": 1,
  "hasNext": false,
  "hasPrevious": false
}

Para encontrar todo lo que necesita atención, filtra por status=failed. Un responseCode de null en un intento significa que tu endpoint no respondió en absoluto — un timeout o un error de red en lugar de un error HTTP.

Estados de entrega

Estado	Significado
`queued`	La entrega está esperando a ser enviada.
`delivering`	Una solicitud HTTP a tu endpoint está en curso.
`delivered`	Tu endpoint confirmó con una respuesta `2xx`.
`failed`	El intento más reciente falló — respuesta no `2xx`, o sin respuesta dentro de 15 segundos. Recuperable mediante reenvío.

Recuperar un evento

GET /v2/events/{id} devuelve el evento completo más cada entrega y cada intento — incluida la respuesta que devolvió tu endpoint:

curl https://api.spherepay.co/v2/events/event_01HXPA3M9R7DEF456 \
  -H "Authorization: Bearer {{api_key}}"

Cada intento registra type (original o replay), attemptedAt, success, responseCode, responseBody (truncado a 200 caracteres, capturado en los fallos para ayudarte a depurar) y latencyMs.

Si tienes un encabezado Sphere-Delivery-Id de una entrega que recibiste, ese es el ID de la entrega — puedes usarlo para correlacionar una solicitud que llega a tus servidores con los registros de entrega e intento que se muestran aquí.

Reenviar una entrega

SpherePay hace exactamente un intento de entrega automático por evento por endpoint — no hay reintentos automáticos. Cuando una entrega falla (tu endpoint estaba caído, agotó el tiempo de espera o devolvió un error), tú decides cuándo volver a enviarla con POST /v2/events/replay/{eventDeliveryId}, usando el ID de la entrega (no el ID del evento):

curl -X POST https://api.spherepay.co/v2/events/replay/eventDelivery_2351653173 \
  -H "Authorization: Bearer {{api_key}}"

Un reenvío vuelve a enviar el payload idéntico byte por byte al mismo endpoint, con un Sphere-Timestamp y un Sphere-Signature nuevos y los encabezados Sphere-Delivery-Type: replay y Sphere-Replay-Reason: manual. Tu ruta de código de verificación es idéntica para originales y reenvíos. Un reenvío exitoso transiciona la entrega a delivered; un reenvío fallido la deja en failed y registra otro intento. En cualquier caso, el historial completo de intentos se conserva.

Los reenvíos se entregan al menos una vez además de lo que tu endpoint ya recibió, y puedes reenviar una entrega que ya tuvo éxito. Asegúrate de que tu handler deduplique usando el id del evento y aplique la verificación de obsolescencia con sequence para que los reenvíos siempre sean seguros.

Recuperación tras una caída

Si tu endpoint estuvo caído durante un período:

Lista los eventos con status=failed y createdStart/createdEnd cubriendo la ventana de la interrupción.
Reenvía cada entrega fallida vía POST /v2/events/replay/{eventDeliveryId}.
Tu manejo de sequence descartará automáticamente cualquier evento reenviado que ya haya sido superado.

Alternativamente, dado que los payloads son mínimos, puedes simplemente volver a consultar el estado actual de los recursos afectados con sus endpoints GET y reconciliar directamente.

Incorporación

Transferencias

Automatización

Webhooks

Datos de referencia

Operacional

Explorar Eventos y Reenviar Entregas

Listar eventos

Estados de entrega

Recuperar un evento

Reenviar una entrega

Recuperación tras una caída

​Listar eventos

​Estados de entrega

​Recuperar un evento

​Reenviar una entrega

​Recuperación tras una caída

Listar eventos

Estados de entrega

Recuperar un evento

Reenviar una entrega

Recuperación tras una caída