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

# Browsing Events and Replaying Deliveries

> Look through every event SpherePay has recorded, inspect delivery attempts and responses, and replay a failed delivery on demand.

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

```bash theme={"dark"}
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:

```json theme={"dark"}
{
  "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
}
```

<Tip>
  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.
</Tip>

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

```bash theme={"dark"}
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`.

<Note>
  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.
</Note>

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

```bash theme={"dark"}
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.

<Warning>
  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](/concepts/webhooks/event-payloads#the-sequence-field) so replays are always safe.
</Warning>

## Recovering from downtime

If your endpoint was down for a period:

1. List events with `status=failed` and `createdStart`/`createdEnd` covering the outage window.
2. Replay each failed delivery via `POST /v2/events/replay/{eventDeliveryId}`.
3. 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.