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

# Webhook Event Types

> Comprehensive list of all webhook events and their payloads

# Webhook Event Types

SwiftPay sends webhooks for various events in your account. Each event follows a standard envelope structure.

## Webhook Structure

Every webhook request sent by SwiftPay has the following structure:

| Field     | Type   | Description                                    |
| --------- | ------ | ---------------------------------------------- |
| `id`      | string | Unique event identifier (e.g., `evt_abc123`)   |
| `type`    | string | The type of event (e.g., `checkout.succeeded`) |
| `created` | string | ISO 8601 timestamp of when the event occurred  |
| `data`    | object | Event-specific payload (see below for types)   |

## Expected Response

Your server should return a **2xx HTTP status code** (e.g., `200 OK`, `201 Created`, `204 No Content`) to acknowledge receipt of the webhook.

* **Timeouts**: SwiftPay waits up to 30 seconds for a response.
* **Retries**: If your server returns any other status code (e.g., `4xx`, `5xx`) or the request times out, SwiftPay will retry the delivery according to the [retry schedule](/guides/webhooks#retry-logic).
* **Body**: The response body is ignored, but we recommend returning a short string like `OK`.

### Headers

Each request includes security headers for verification:

| Header                | Description                                                                     |
| --------------------- | ------------------------------------------------------------------------------- |
| `X-Webhook-Signature` | HMAC SHA-256 signature for verification. Format: `t={timestamp},v1={signature}` |
| `User-Agent`          | `SwiftPay-Webhooks/1.0`                                                         |

## Checkout Events

### `checkout.succeeded`

Occurs when a checkout session is successfully completed and payment is received.

```json theme={null}
{
   "id": "evt_checkout_abc123",
   "type": "checkout.succeeded",
   "created": "2024-01-15T10:30:00Z",
   "data": {
      "sessionId": "sess_abc123",
      "amount": 2999,
      "amountInDecimals": "29.99",
      "currency": "USD",
      "customerEmail": "customer@example.com",
      "customerName": "John Doe",
      "timestamp": "2024-01-15T10:30:00Z",
      "shipping": {
         "addressLine1": "123 Main St",
         "city": "San Francisco",
         "state": "CA",
         "postalCode": "94102",
         "country": "US"
      }
   }
}
```

#### Payload Fields

| Field              | Type    | Description                                      |
| ------------------ | ------- | ------------------------------------------------ |
| `sessionId`        | string  | Unique checkout session identifier               |
| `amount`           | integer | Total amount in cents                            |
| `amountInDecimals` | string  | Total amount formatted as decimal (e.g. "29.99") |
| `currency`         | string  | Three-letter ISO currency code                   |
| `customerEmail`    | string  | Email address of the customer                    |
| `customerName`     | string  | Full name of the customer                        |
| `timestamp`        | string  | ISO 8601 timestamp of completion                 |
| `shipping`         | object  | Shipping address details (if collected)          |

### `checkout.failed`

Occurs when a checkout session fails (e.g., payment declined).

```json theme={null}
{
   "id": "evt_checkout_def456",
   "type": "checkout.failed",
   "created": "2024-01-15T10:35:00Z",
   "data": {
      "sessionId": "sess_def456",
      "amount": 2999,
      "amountInDecimals": "29.99",
      "currency": "USD",
      "customerEmail": "customer@example.com",
      "errorMessage": "Insufficient funds",
      "failedAt": "2024-01-15T10:35:00Z"
   }
}
```

#### Payload Fields

| Field              | Type    | Description                                      |
| ------------------ | ------- | ------------------------------------------------ |
| `sessionId`        | string  | Unique checkout session identifier               |
| `amount`           | integer | Total amount in cents                            |
| `amountInDecimals` | string  | Total amount formatted as decimal (e.g. "29.99") |
| `currency`         | string  | Three-letter ISO currency code                   |
| `customerEmail`    | string  | Email address of the customer                    |
| `errorMessage`     | string  | Reason for the payment failure                   |
| `failedAt`         | string  | ISO 8601 timestamp of failure                    |

## Refund Events

### `refund.completed`

Occurs when a refund is successfully processed.

```json theme={null}
{
   "id": "evt_refund_def456",
   "type": "refund.completed",
   "created": "2024-01-15T11:05:00Z",
   "data": {
      "refundId": "ref_abc123",
      "sessionId": "sess_abc123",
      "amount": 2999,
      "amountInDecimals": "29.99",
      "currency": "USD",
      "completedAt": "2024-01-15T11:05:00Z"
   }
}
```

#### Payload Fields

| Field              | Type    | Description                                       |
| ------------------ | ------- | ------------------------------------------------- |
| `refundId`         | string  | Unique refund identifier                          |
| `sessionId`        | string  | Original checkout session identifier              |
| `amount`           | integer | Refund amount in cents                            |
| `amountInDecimals` | string  | Refund amount formatted as decimal (e.g. "29.99") |
| `currency`         | string  | Three-letter ISO currency code                    |
| `completedAt`      | string  | ISO 8601 timestamp of completion                  |

### `refund.failed`

Occurs when a refund attempt fails.

```json theme={null}
{
   "id": "evt_refund_ghi789",
   "type": "refund.failed",
   "created": "2024-01-15T11:10:00Z",
   "data": {
      "refundId": "ref_abc123",
      "sessionId": "sess_abc123",
      "amount": 2999,
      "amountInDecimals": "29.99",
      "currency": "USD",
      "errorMessage": "Processor error",
      "failedAt": "2024-01-15T11:10:00Z"
   }
}
```

#### Payload Fields

| Field              | Type    | Description                                       |
| ------------------ | ------- | ------------------------------------------------- |
| `refundId`         | string  | Unique refund identifier                          |
| `sessionId`        | string  | Original checkout session identifier              |
| `amount`           | integer | Refund amount in cents                            |
| `amountInDecimals` | string  | Refund amount formatted as decimal (e.g. "29.99") |
| `currency`         | string  | Three-letter ISO currency code                    |
| `errorMessage`     | string  | Reason for the refund failure                     |
| `failedAt`         | string  | ISO 8601 timestamp of failure                     |

## Withdrawal Events

### `withdrawal.paid`

Occurs when a withdrawal has been successfully paid out.

```json theme={null}
{
   "id": "evt_withdrawal_def456",
   "type": "withdrawal.paid",
   "created": "2024-01-16T09:00:00Z",
   "data": {
      "withdrawalId": "wd_abc123",
      "amount": 50000,
      "amountInDecimals": "500.00",
      "currency": "USD",
      "destinationType": "bank_account",
      "completedAt": "2024-01-16T09:00:00Z"
   }
}
```

#### Payload Fields

| Field              | Type    | Description                                            |
| ------------------ | ------- | ------------------------------------------------------ |
| `withdrawalId`     | string  | Unique withdrawal identifier                           |
| `amount`           | integer | Withdrawal amount in cents                             |
| `amountInDecimals` | string  | Withdrawal amount formatted as decimal (e.g. "500.00") |
| `currency`         | string  | Three-letter ISO currency code                         |
| `destinationType`  | string  | Type of destination (e.g. `bank_account`, `crypto`)    |
| `completedAt`      | string  | ISO 8601 timestamp of completion                       |

### `withdrawal.failed`

Occurs when a withdrawal attempt fails.

```json theme={null}
{
   "id": "evt_withdrawal_ghi789",
   "type": "withdrawal.failed",
   "created": "2024-01-16T09:05:00Z",
   "data": {
      "withdrawalId": "wd_abc123",
      "amount": 50000,
      "amountInDecimals": "500.00",
      "currency": "USD",
      "errorMessage": "Invalid bank details",
      "failedAt": "2024-01-16T09:05:00Z"
   }
}
```

#### Payload Fields

| Field              | Type    | Description                                            |
| ------------------ | ------- | ------------------------------------------------------ |
| `withdrawalId`     | string  | Unique withdrawal identifier                           |
| `amount`           | integer | Withdrawal amount in cents                             |
| `amountInDecimals` | string  | Withdrawal amount formatted as decimal (e.g. "500.00") |
| `currency`         | string  | Three-letter ISO currency code                         |
| `errorMessage`     | string  | Reason for the withdrawal failure                      |
| `failedAt`         | string  | ISO 8601 timestamp of failure                          |