Sendcloud Event Subscriptions API v3
Manage typed event subscriptions and webhook delivery connections — register endpoints, list subscriptions, and broadcast test events.
OpenAPI Specification
openapi: 3.1.0
info:
title: Event Subscriptions API
version: 3.0.0
description: >-
**BETA** - 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.
All resources are scoped to the authenticated user's organization.
contact:
name: Sendcloud API Support
email: contact@sendcloud.com
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://panel.sendcloud.sc/api/v3
description: Sendcloud Production
tags:
- name: Connections
- name: Subscriptions
- name: OAuth2
- name: Broadcast
- name: Events
paths:
/event-subscriptions/connections:
post:
summary: Create a connection
description: >-
Create a new connection to an external endpoint where event
notifications will be delivered.
tags:
- Connections
operationId: sc-public-v3-scp-post-create_connection
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds: []
x-mint:
href: /api/v3/event-subscriptions/create-a-connection
content: >-
Create a new connection that defines an external endpoint for event
delivery.
**Webhook connections** require a `url` and optionally authentication
configuration. Supported authentication types are `none`, `bearer`,
`basic`, and `api_key`.
**Klaviyo connections** require only the `type` field set to `klaviyo`
with an empty `configuration` object. After creating the connection,
use the [Start OAuth2
authorization](/api/v3/event-subscriptions/start-oauth2-authorization)
endpoint to connect your Klaviyo account.
<Info>
Webhook URLs must be publicly accessible and respond with a `2xx` status code to acknowledge event delivery.
</Info>
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/connection-create-request'
examples:
WebhookConnection:
summary: Create a webhook connection with bearer auth
value:
type: webhook
configuration:
url: https://example.com/webhooks/sendcloud
auth_type: bearer
auth_config:
token: my-secret-token
extra_headers:
X-Custom-Header: my-value
WebhookConnectionNoAuth:
summary: Create a webhook connection without auth
value:
type: webhook
configuration:
url: https://example.com/webhooks/sendcloud
auth_type: none
KlaviyoConnection:
summary: Create a Klaviyo connection
value:
type: klaviyo
configuration: {}
responses:
'201':
description: Created
content:
application/json:
schema:
description: Connection created
type: object
properties:
data:
$ref: '#/components/schemas/connection'
examples:
WebhookCreated:
summary: Webhook connection created
value:
data:
id: 1
type: webhook
configuration:
url: https://example.com/webhooks/sendcloud
auth_type: bearer
extra_headers:
X-Custom-Header: my-value
created_at: '2026-01-15T10:30:00Z'
updated_at: '2026-01-15T10:30:00Z'
KlaviyoCreated:
summary: Klaviyo connection created
value:
data:
id: 2
type: klaviyo
configuration: {}
created_at: '2026-01-15T10:30:00Z'
updated_at: '2026-01-15T10:30:00Z'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errors'
examples:
ValidationError:
summary: Validation error
value:
errors:
- detail: This field is required.
status: '400'
source:
pointer: /data/type
code: required
'429':
description: Throttled
get:
summary: List connections
description: Retrieve all connections for the authenticated user's organization.
tags:
- Connections
operationId: sc-public-v3-scp-get-list_connections
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds: []
x-mint:
href: /api/v3/event-subscriptions/list-connections
parameters:
- schema:
type: string
enum:
- webhook
- klaviyo
in: query
name: connection_type
description: Filter by connection type.
responses:
'200':
description: OK
content:
application/json:
schema:
description: List of connections
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/connection'
required:
- data
examples:
ListConnections:
summary: List of connections
value:
data:
- id: 1
type: webhook
configuration:
url: https://example.com/webhooks/sendcloud
auth_type: bearer
extra_headers:
X-Custom-Header: my-value
created_at: '2026-01-15T10:30:00Z'
updated_at: '2026-01-15T10:30:00Z'
- id: 2
type: klaviyo
configuration: {}
created_at: '2026-01-16T09:00:00Z'
updated_at: '2026-01-16T09:00:00Z'
'429':
description: Throttled
/event-subscriptions/connections/{id}:
parameters:
- schema:
type: integer
in: path
name: id
description: The id of the connection.
required: true
get:
summary: Get a connection
description: Retrieve a specific connection by its id.
tags:
- Connections
operationId: sc-public-v3-scp-get-connection
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds: []
x-mint:
href: /api/v3/event-subscriptions/get-a-connection
responses:
'200':
description: OK
content:
application/json:
schema:
description: Connection details
type: object
properties:
data:
$ref: '#/components/schemas/connection'
examples:
GetConnection:
summary: Get a webhook connection
value:
data:
id: 1
type: webhook
configuration:
url: https://example.com/webhooks/sendcloud
auth_type: bearer
extra_headers:
X-Custom-Header: my-value
created_at: '2026-01-15T10:30:00Z'
updated_at: '2026-01-15T10:30:00Z'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errors'
patch:
summary: Update a connection
description: >-
Update an existing connection by its id. Only the fields provided in the
request body will be updated.
tags:
- Connections
operationId: sc-public-v3-scp-patch-connection
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds: []
x-mint:
href: /api/v3/event-subscriptions/update-a-connection
content: >-
Update the configuration of an existing connection.
Only the fields provided in the request body will be updated. For
example, you can update just the webhook URL or authentication
settings without changing other fields.
<Warning>
Updating a connection's configuration may affect all subscriptions that use this connection.
</Warning>
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/connection-update-request'
examples:
UpdateWebhookUrl:
summary: Update the webhook URL
value:
configuration:
url: https://example.com/webhooks/sendcloud-v2
UpdateAuth:
summary: Update authentication settings
value:
configuration:
auth_type: api_key
auth_config:
header_name: X-Api-Key
api_key: my-new-api-key
responses:
'200':
description: OK
content:
application/json:
schema:
description: Updated connection
type: object
properties:
data:
$ref: '#/components/schemas/connection'
examples:
UpdatedConnection:
summary: Updated webhook connection
value:
data:
id: 1
type: webhook
configuration:
url: https://example.com/webhooks/sendcloud-v2
auth_type: api_key
extra_headers:
X-Custom-Header: my-value
created_at: '2026-01-15T10:30:00Z'
updated_at: '2026-01-20T14:00:00Z'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errors'
examples:
ValidationError:
summary: Validation error
value:
errors:
- detail: Enter a valid URL.
status: '400'
source:
pointer: /data/configuration/url
code: invalid
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errors'
delete:
summary: Delete a connection
description: >-
Delete a specific connection by its id. Any subscriptions associated
with this connection will also be deleted.
tags:
- Connections
operationId: sc-public-v3-scp-delete-connection
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds: []
x-mint:
href: /api/v3/event-subscriptions/delete-a-connection
content: |-
Delete a connection and all its associated subscriptions.
<Warning>
This action is irreversible. All subscriptions linked to this connection will be permanently deleted and event delivery will stop immediately.
</Warning>
responses:
'204':
description: No Content
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errors'
/event-subscriptions/connections/{id}/authorization:
parameters:
- schema:
type: integer
in: path
name: id
description: The id of the connection to authorize.
required: true
post:
summary: Start OAuth2 authorization
description: >-
Initiate the OAuth2 authorization flow for a connection that requires it
(e.g., Klaviyo). Returns an authorization URL to redirect the user to.
tags:
- OAuth2
operationId: sc-public-v3-scp-post-start_authorization
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds: []
x-mint:
href: /api/v3/event-subscriptions/start-oauth2-authorization
content: >-
Start the OAuth2 authorization flow for a Klaviyo connection. This
endpoint returns an authorization URL that the user should be
redirected to in their browser.
After the user authorizes access, the OAuth provider will redirect
back to the Sendcloud callback URL, completing the connection setup.
<Steps>
<Step title="Create a Klaviyo connection">
Use the [Create a connection](/api/v3/event-subscriptions/create-a-connection) endpoint with `type: "klaviyo"`.
</Step>
<Step title="Start OAuth2 authorization">
Call this endpoint to get the authorization URL.
</Step>
<Step title="Redirect the user">
Open the `authorization_url` in the user's browser to complete the OAuth2 flow.
</Step>
</Steps>
responses:
'200':
description: OK
content:
application/json:
schema:
description: OAuth2 authorization URL
type: object
properties:
data:
$ref: '#/components/schemas/connection-authorization-response'
examples:
AuthorizationUrl:
summary: OAuth2 authorization URL
value:
data:
authorization_url: >-
https://www.klaviyo.com/oauth/authorize?client_id=sendcloud&response_type=code&redirect_uri=https%3A%2F%2Fpanel.sendcloud.sc%2Fapi%2Fv3%2Fevent-subscriptions%2Fconnections%2Fauthorization%2Fcallback&state=abc123
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errors'
/event-subscriptions/subscriptions:
post:
summary: Create a subscription
description: >-
Create a new subscription that routes events of a specific type to a
connection.
tags:
- Subscriptions
operationId: sc-public-v3-scp-post-create_subscription
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds: []
x-mint:
href: /api/v3/event-subscriptions/create-a-subscription
content: >-
Create a subscription that routes a specific event type to a
connection for delivery.
A subscription links an event type (e.g., `parcels.event.created`) to
a connection endpoint. When the event occurs, the event payload is
delivered to the connection's configured endpoint.
<Info>
Subscriptions are active by default. Set `is_active` to `false` to create a paused subscription.
</Info>
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/subscription-create-request'
examples:
CreateSubscription:
summary: Create a subscription for parcel events
value:
connection_id: 1
event_type: parcels.event.created
is_active: true
responses:
'201':
description: Created
content:
application/json:
schema:
description: Subscription created
type: object
properties:
data:
$ref: '#/components/schemas/subscription'
examples:
SubscriptionCreated:
summary: Subscription created
value:
data:
id: 1
connection_id: 1
event_type: parcels.event.created
is_active: true
created_at: '2026-01-15T11:00:00Z'
updated_at: '2026-01-15T11:00:00Z'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errors'
examples:
ValidationError:
summary: Validation error
value:
errors:
- detail: This field is required.
status: '400'
source:
pointer: /data/connection_id
code: required
'429':
description: Throttled
get:
summary: List subscriptions
description: Retrieve all subscriptions for the authenticated user's organization.
tags:
- Subscriptions
operationId: sc-public-v3-scp-get-list_subscriptions
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds: []
x-mint:
href: /api/v3/event-subscriptions/list-subscriptions
parameters:
- schema:
type: string
in: query
name: event_type
description: Filter by event type.
- schema:
type: boolean
in: query
name: is_active
description: Filter by active status.
responses:
'200':
description: OK
content:
application/json:
schema:
description: List of subscriptions
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/subscription'
required:
- data
examples:
ListSubscriptions:
summary: List of subscriptions
value:
data:
- id: 1
connection_id: 1
event_type: parcels.event.created
is_active: true
created_at: '2026-01-15T11:00:00Z'
updated_at: '2026-01-15T11:00:00Z'
- id: 2
connection_id: 2
event_type: parcels.event.created
is_active: false
created_at: '2026-01-16T09:15:00Z'
updated_at: '2026-01-16T09:15:00Z'
'429':
description: Throttled
/event-subscriptions/subscriptions/{id}:
parameters:
- schema:
type: integer
in: path
name: id
description: The id of the subscription.
required: true
get:
summary: Get a subscription
description: Retrieve a specific subscription by its id.
tags:
- Subscriptions
operationId: sc-public-v3-scp-get-subscription
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds: []
x-mint:
href: /api/v3/event-subscriptions/get-a-subscription
responses:
'200':
description: OK
content:
application/json:
schema:
description: Subscription details
type: object
properties:
data:
$ref: '#/components/schemas/subscription'
examples:
GetSubscription:
summary: Get a subscription
value:
data:
id: 1
connection_id: 1
event_type: parcels.event.created
is_active: true
created_at: '2026-01-15T11:00:00Z'
updated_at: '2026-01-15T11:00:00Z'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errors'
patch:
summary: Update a subscription
description: >-
Update an existing subscription by its id. Only the fields provided in
the request body will be updated.
tags:
- Subscriptions
operationId: sc-public-v3-scp-patch-subscription
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds: []
x-mint:
href: /api/v3/event-subscriptions/update-a-subscription
content: >-
Update an existing subscription. You can change the connection, event
type, or toggle the active state.
<Info>
Set `is_active` to `false` to pause event delivery without deleting the subscription.
</Info>
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/subscription-update-request'
examples:
PauseSubscription:
summary: Pause a subscription
value:
is_active: false
ChangeConnection:
summary: Route events to a different connection
value:
connection_id: 2
responses:
'200':
description: OK
content:
application/json:
schema:
description: Updated subscription
type: object
properties:
data:
$ref: '#/components/schemas/subscription'
examples:
UpdatedSubscription:
summary: Updated subscription
value:
data:
id: 1
connection_id: 2
event_type: parcels.event.created
is_active: false
created_at: '2026-01-15T11:00:00Z'
updated_at: '2026-01-20T14:30:00Z'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errors'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errors'
delete:
summary: Delete a subscription
description: >-
Delete a specific subscription by its id. Event delivery for this
subscription will stop immediately.
tags:
- Subscriptions
operationId: sc-public-v3-scp-delete-subscription
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds: []
x-mint:
href: /api/v3/event-subscriptions/delete-a-subscription
responses:
'204':
description: No Content
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errors'
/event-subscriptions/broadcast/test/{subscription_id}:
parameters:
- schema:
type: integer
in: path
name: subscription_id
description: The id of the subscription to send a test event to.
required: true
post:
summary: Broadcast test event
description: >-
Send a test event to the connection endpoint configured for a specific
subscription. Use this to verify that your connection is set up
correctly before relying on it for production events.
tags:
- Broadcast
operationId: sc-public-v3-scp-post-test_broadcast
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds: []
x-mint:
href: /api/v3/event-subscriptions/test-event-delivery
content: >-
Send a test event to the connection endpoint configured for this
subscription. This is useful for verifying that your webhook URL or
Klaviyo integration is set up correctly.
The test event will contain a sample payload matching the
subscription's event type.
<Info>
The test broadcast will use the same authentication and headers configured on the connection.
</Info>
responses:
'200':
description: OK
content:
application/json:
schema:
description: Test broadcast result
type: object
properties:
data:
$ref: '#/components/schemas/broadcast-result'
examples:
SuccessfulBroadcast:
summary: Successful test broadcast
value:
data:
success: true
status_code: 200
response_body: OK
FailedBroadcast:
summary: Failed test broadcast
value:
data:
success: false
status_code: 500
response_body: Internal Server Error
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errors'
webhooks:
ParcelEventCreated:
post:
operationId: sc-public-v3-event-subscriptions-parcel_event_created
summary: Parcel event created
description: >-
Delivered to your connection endpoint when a parcel tracking event
occurs (e.g., a status change such as shipped, delivered, or returned).
Subscribe to this event type using `parcels.event.created` when creating
a subscription.
x-mint:
href: /api/v3/event-subscriptions/parcel-event-created
tags:
- Events
security: []
requestBody:
description: Event data delivered to your endpoint
content:
application/json:
schema:
$ref: '#/components/schemas/ParcelEventCreatedPayload'
examples:
InTransit:
summary: Parcel in transit
value:
event_type: parcels.event.created
data:
parcel:
parcel_id: 12345678
tracking_number: 3SYZXG132912330
carrier_code: dpd
announced_at: '2026-01-15T10:00:00Z'
event:
event_type: carrier
timestamp: '2026-01-15T10:30:00Z'
phase: in_transit
exception: none
status_type: success
sub_status: none
description: Parcel is on its way
end_of_tracking: false
is_offered: false
is_carrier_responsible: null
is_returned: false
location_details:
city: Eindhoven
country: NL
house_number: null
postal_code: null
street: null
service_point_id: null
depot: null
extra_data: null
Delivered:
summary: Parcel delivered
value:
event_type: parcels.event.created
data:
parcel:
parcel_id: 12345678
tracking_number: 3SYZXG132912330
carrier_code: dpd
announced_at: '2026-01-15T10:00:00Z'
event:
event_type: carrier
timestamp: '2026-01-16T14:22:00Z'
phase: delivered
exception: none
status_type: success
sub_status: none
description: Parcel has been delivered
end_of_tracking: true
is_offered: true
is_carrier_responsible: null
is_returned: false
location_details: null
extra_data: null
responses:
'200':
description: Return a 2xx status to acknowledge receipt of the event.
components:
schemas:
ParcelEventCreatedPayload:
type: object
description: >-
Event payload delivered to your endpoint when a parcel tracking event
occurs.
required:
- event_type
- data
properties:
event_type:
type: string
description: The event type identifier.
example: parcels.event.created
enum:
- parcels.event.created
data:
type: object
description: The event payload.
required:
- parcel
- event
properties:
parcel:
$ref: '#/components/schemas/WebhookParcelData'
event:
$ref: '#/components/schemas/WebhookEventData'
WebhookParcelData:
type: object
description: Parcel identifiers included in event deliveries.
required:
- parcel_id
- carrier_code
properties:
parcel_id:
type: integer
description: Sendcloud parcel identifier.
example: 12345678
tracking_number:
type:
- string
- 'null'
description: Carrier-issued tracking number.
example: 3SYZXG132912330
carrier_code:
type: string
description: Short carrier code (e.g. `dpd`, `dhl`, `postnl`).
example: dpd
announced_at:
type:
- string
- 'null'
format: date-time
description: >-
ISO 8601 timestamp of when the carrier was announced for this
parcel.
example: '2026-01-15T10:00:00Z'
WebhookEventData:
type: object
description: Parcel tracking event data.
required:
- event_type
- timestamp
- phase
- exception
- status_type
- sub_status
properties:
event_type:
$ref: '#/components/schemas/parcel-event-type'
timestamp:
type: string
format: date-time
description: ISO 8601 timestamp of when the event occurred.
example: '2026-01-15T10:30:00Z'
phase:
$ref: '#/components/schemas/parcel-event-phase'
exception:
$ref: '#/components/schemas/parcel-event-exception'
status_type:
$ref: '#/components/schemas/parcel-event-status-type'
sub_status:
$ref: '#/components/schemas/parcel-event-sub-status'
description:
type:
- string
- 'null'
description: Human-readable carrier description of the event.
example: Parcel is on its way
end_of_tracking:
type:
- boolean
- 'null'
description: True when there will be no further tracking updates.
example: false
is_offere
# --- truncated at 32 KB (46 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sendcloud/refs/heads/main/openapi/sendcloud-v3-event-subscriptions-openapi.yml