BETA - The Event Subscriptions API is currently in beta. Endpoints and behavior may change as the feature evolves.
- 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" } |
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 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.
