Browsing Events and Replaying Deliveries

Every event SpherePay creates — and every attempt to deliver it — is recorded and queryable. Use the Events API to audit what happened, diagnose failed deliveries, and re-send any delivery to your endpoint. Dashboard views for browsing and replaying events are coming soon; today these controls live in the API.

List events

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

Parameter	Description
`type`	Event type filter — an exact name (`transfer.succeeded`), a resource wildcard (`transfer.`), or ``.
`status`	Filter by delivery status: `queued`, `delivering`, `delivered`, or `failed`.
`webhookEndpointId`	Only events with a delivery to the given endpoint.
`createdStart` / `createdEnd`	Inclusive ISO 8601 bounds on event creation time.
`page` / `limit`	Pagination (defaults `1` / `10`, maximum limit `100`).

Each list item summarizes the event and its most recent delivery:

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

To find everything that needs attention, filter by status=failed. A responseCode of null on an attempt means your endpoint did not respond at all — a timeout or network error rather than an HTTP error.

Delivery statuses

Status	Meaning
`queued`	The delivery is waiting to be sent.
`delivering`	An HTTP request to your endpoint is in flight.
`delivered`	Your endpoint acknowledged with a `2xx` response.
`failed`	The most recent attempt failed — non-`2xx` response, or no response within 15 seconds. Recoverable via replay.

Retrieve an event

GET /v2/events/{id} returns the full event plus every delivery and every attempt — including the response your endpoint returned:

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

Each attempt records type (original or replay), attemptedAt, success, responseCode, responseBody (truncated to 200 characters, captured on failures to help you debug), and latencyMs.

If you are holding a Sphere-Delivery-Id header from a delivery you received, that is the delivery’s ID — you can use it to correlate a request hitting your servers with the delivery and attempt records shown here.

Replaying a delivery

SpherePay makes exactly one automatic delivery attempt per event per endpoint — there are no automatic retries. When a delivery fails (your endpoint was down, timed out, or returned an error), you decide when to re-send it with POST /v2/events/replay/{eventDeliveryId}, using the delivery ID (not the event ID):

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

A replay re-sends the byte-for-byte identical payload to the same endpoint, with a fresh Sphere-Timestamp and Sphere-Signature and the headers Sphere-Delivery-Type: replay and Sphere-Replay-Reason: manual. Your verification code path is identical for originals and replays. A successful replay transitions the delivery to delivered; a failed replay leaves it failed and records another attempt. Either way, the full attempt history is preserved.

Replays are delivered at-least-once on top of whatever your endpoint already received, and you can replay a delivery that already succeeded. Make sure your handler deduplicates on the event id and applies the sequence staleness check so replays are always safe.

Recovering from downtime

If your endpoint was down for a period:

List events with status=failed and createdStart/createdEnd covering the outage window.
Replay each failed delivery via POST /v2/events/replay/{eventDeliveryId}.
Your sequence handling will automatically discard any replayed event that has since been superseded.

Alternatively, because payloads are minimal, you can simply re-fetch the current state of affected resources with their GET endpoints and reconcile directly.

Onboarding

Transfers

Automation

Webhooks

Reference data

Operational

Browsing Events and Replaying Deliveries

List events

Delivery statuses

Retrieve an event

Replaying a delivery

Recovering from downtime

​List events

​Delivery statuses

​Retrieve an event

​Replaying a delivery

​Recovering from downtime

List events

Delivery statuses

Retrieve an event

Replaying a delivery

Recovering from downtime