> ## Documentation Index
> Fetch the complete documentation index at: https://docs.swiftpay.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# List Webhook Events

> List webhook event delivery history

# List Webhook Events

Returns a list of recent webhook events that have been delivered or attempted.

## Request

<ParamField header="Authorization" type="string" required>
  Bearer token with your API key
</ParamField>

<ParamField query="limit" type="integer" default="50">
  Number of results to return (1-100)
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Whether the request was successful
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="events" type="array">
      Array of webhook event objects

      <Expandable title="event object">
        <ResponseField name="id" type="string">
          Unique event identifier
        </ResponseField>

        <ResponseField name="eventId" type="string">
          External event ID (e.g. payment ID)
        </ResponseField>

        <ResponseField name="type" type="string">
          Type of event (e.g., `checkout.succeeded`, `refund.completed`)
        </ResponseField>

        <ResponseField name="data" type="object">
          Event payload data
        </ResponseField>

        <ResponseField name="createdAt" type="string">
          ISO 8601 creation timestamp
        </ResponseField>

        <ResponseField name="deliveries" type="array">
          History of delivery attempts for this event

          <Expandable title="delivery object">
            <ResponseField name="id" type="string">
              Unique delivery identifier
            </ResponseField>

            <ResponseField name="endpointId" type="string">
              Target endpoint ID
            </ResponseField>

            <ResponseField name="endpointUrl" type="string">
              Target endpoint URL
            </ResponseField>

            <ResponseField name="status" type="string">
              Delivery status: `pending`, `success`, `failed`
            </ResponseField>

            <ResponseField name="attemptCount" type="integer">
              Number of attempts made
            </ResponseField>

            <ResponseField name="maxAttempts" type="integer">
              Maximum number of retry attempts
            </ResponseField>

            <ResponseField name="responseStatusCode" type="integer">
              HTTP status code from your server
            </ResponseField>

            <ResponseField name="responseBody" type="string">
              Response body from your server
            </ResponseField>

            <ResponseField name="errorMessage" type="string">
              Error message if delivery failed
            </ResponseField>

            <ResponseField name="createdAt" type="string">
              ISO 8601 creation timestamp
            </ResponseField>

            <ResponseField name="lastAttemptAt" type="string">
              ISO 8601 timestamp of last attempt
            </ResponseField>

            <ResponseField name="nextRetryAt" type="string">
              ISO 8601 timestamp of next scheduled retry
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.swiftpay.cx/api/webhooks/events?limit=10" \
    -H "Authorization: Bearer mp_live_your_api_key"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
     "https://api.swiftpay.cx/api/webhooks/events?limit=10",
     {
        headers: {
           Authorization: "Bearer mp_live_your_api_key",
        },
     },
  );

  const result = await response.json();

  result.data.events.forEach((event) => {
     console.log(`${event.type} (${event.id})`);
     event.deliveries.forEach((delivery) => {
        console.log(`  -> ${delivery.endpointUrl}: ${delivery.status}`);
     });
  });
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.swiftpay.cx/api/webhooks/events',
      headers={'Authorization': 'Bearer mp_live_your_api_key'},
      params={'limit': 10}
  )

  events = response.json()['data']['events']

  for event in events:
      print(f"{event['type']} ({event['id']})")
      for delivery in event['deliveries']:
          print(f"  -> {delivery['endpointUrl']}: {delivery['status']}")
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "data": {
      "events": [
        {
          "id": "evt_abc123",
          "eventId": "sess_xyz789",
          "type": "checkout.succeeded",
          "created": 1640995200,
          "data": {
            "id": "sess_xyz789",
            "amount": 10000,
            "currency": "USD"
          },
          "createdAt": "2024-01-15T10:30:00Z",
          "deliveries": [
            {
              "id": "del_123",
              "endpointId": "wh_abc123",
              "endpointUrl": "https://yoursite.com/webhooks",
              "status": "success",
              "attemptCount": 1,
              "maxAttempts": 5,
              "responseStatusCode": 200,
              "responseBody": "OK",
              "errorMessage": null,
              "createdAt": "2024-01-15T10:30:01Z",
              "lastAttemptAt": "2024-01-15T10:30:01Z",
              "nextRetryAt": null
            }
          ]
        }
      ]
    }
  }
  ```
</ResponseExample>

## Event Statuses

| Status    | Description                                    |
| --------- | ---------------------------------------------- |
| `pending` | Event queued for delivery                      |
| `success` | Successfully delivered (received 2xx response) |
| `failed`  | All retry attempts exhausted                   |