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

# Event Subscriptions API overview

<Note>
  **BETA** - The Event Subscriptions API is currently in beta. Endpoints and behavior may change as the feature evolves.
</Note>

The Event Subscriptions API allows you to subscribe to parcel events and have them delivered to external endpoints such as webhooks or Klaviyo.

This API uses a two-part model:

* **Connections** define *where* events are delivered (e.g., a webhook URL or a Klaviyo account).
* **Subscriptions** define *which* events are routed to a connection.

## Supported connection types

| Type      | Description                                                      |
| --------- | ---------------------------------------------------------------- |
| `webhook` | Delivers event payloads via HTTP POST to a URL you specify.      |
| `klaviyo` | Sends event data to your Klaviyo account via OAuth2 integration. |

## Supported event types

| Event type              | Description                                                                                           |
| ----------------------- | ----------------------------------------------------------------------------------------------------- |
| `parcels.event.created` | Triggered when a parcel event occurs (e.g., a status change such as shipped, delivered, or returned). |

## Webhook authentication

When creating a webhook connection, you can configure authentication for event delivery requests. The following authentication types are supported:

| Auth type | Description                                      | Configuration                                           |
| --------- | ------------------------------------------------ | ------------------------------------------------------- |
| `none`    | No authentication.                               | No `auth_config` needed.                                |
| `bearer`  | Bearer token in the `Authorization` header.      | `{ "token": "your-token" }`                             |
| `basic`   | Basic authentication with username and password. | `{ "username": "user", "password": "pass" }`            |
| `api_key` | API key sent as a custom header.                 | `{ "header_name": "X-Api-Key", "api_key": "your-key" }` |

You can also add custom headers to webhook requests using the `extra_headers` field.

## Retry behavior

When delivering events to a webhook endpoint, Sendcloud will retry failed deliveries up to **5 times** using exponential backoff. A delivery is considered failed when the endpoint returns a non-2xx HTTP status code or is unreachable.

## Testing event delivery

You can verify that your connection is configured correctly by using the [Broadcast test event](/api/v3/event-subscriptions/test-event-delivery) (`/broadcast/test/{subscription_id}`) endpoint. This sends a sample event payload to the connection endpoint and returns the result, including the HTTP status code and response body.