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

# Create a connection

> Create a new connection to an external endpoint where event notifications will be delivered.

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>


## OpenAPI

````yaml /.openapi/v3/event-subscriptions/openapi.yaml post /event-subscriptions/connections
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
security: []
tags:
  - name: Connections
  - name: Subscriptions
  - name: OAuth2
  - name: Broadcast
  - name: Events
paths:
  /event-subscriptions/connections:
    post:
      tags:
        - Connections
      summary: Create a connection
      description: >-
        Create a new connection to an external endpoint where event
        notifications will be delivered.
      operationId: sc-public-v3-scp-post-create_connection
      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
      security:
        - HTTPBasicAuth: []
        - OAuth2ClientCreds: []
components:
  schemas:
    connection-create-request:
      title: Create Connection request
      description: Request body for creating a new connection.
      type: object
      required:
        - type
        - configuration
      properties:
        type:
          type: string
          description: The type of connection.
          enum:
            - webhook
            - klaviyo
        configuration:
          type: object
          description: >-
            The configuration for the connection. The shape depends on the
            connection type.


            For `webhook` connections, see the webhook configuration fields.

            For `klaviyo` connections, configuration can be an empty object as
            credentials are managed via OAuth2.
    connection:
      title: Connection
      description: >-
        A connection defines an external endpoint where event notifications are
        delivered.
      type: object
      properties:
        id:
          type: integer
          format: int64
          minimum: 1
          description: Unique identifier of the connection.
        type:
          type: string
          description: The type of connection.
          enum:
            - webhook
            - klaviyo
        configuration:
          type: object
          description: >-
            The configuration for the connection. The shape depends on the
            connection type.
        created_at:
          type: string
          format: date-time
          description: >-
            The date and time when the connection was created, in ISO 8601
            format.
        updated_at:
          type: string
          format: date-time
          description: >-
            The date and time when the connection was last updated, in ISO 8601
            format.
    errors:
      title: Errors
      type: object
      description: A standardized format for errors in JSON:API responses.
      properties:
        errors:
          type:
            - array
            - object
          items:
            type: object
            allOf:
              - $ref: '#/components/schemas/ErrorObject'
            required:
              - status
              - code
              - detail
    ErrorObject:
      title: Error
      type: object
      description: Error in a JSON:API error format
      properties:
        id:
          type: string
          description: A unique identifier for the error.
        links:
          type: object
          description: >-
            A set of hyperlinks that provide additional information about the
            error.
          properties:
            about:
              type: string
              description: A URL that provides additional information about the error.
        status:
          type: string
          format: int32
          description: The HTTP status code of the error.
          minLength: 1
        code:
          type: string
          description: A unique error code for the error, in snake case format.
          minLength: 1
          enum:
            - unknown_field
            - invalid
            - forbidden
            - invalid_choice
            - min_value
            - 'null'
            - not_found
            - required
            - not_a_list
            - non_field_errors
            - authentication_failed
            - validation_error
            - parcel_announcement_error
        title:
          type: string
          description: A short, human-readable summary of the error.
          minLength: 1
        detail:
          type: string
          description: A human-readable explanation of the error.
          minLength: 1
        source:
          type: object
          description: >-
            An object that identifies the source of the error within the request
            payload.
          properties:
            pointer:
              type: string
              description: >-
                A `JSON` pointer to the location of the error within the request
                payload.
            parameter:
              type: string
              description: The name of the `query` parameter that caused the error.
            header:
              type: string
              description: The name of the `header` parameter that caused the error.
        meta:
          type: object
          description: Additional metadata about the error.
  securitySchemes:
    HTTPBasicAuth:
      type: http
      description: >-
        Basic Authentication using API key and secrets is currently the main
        authentication mechanism.
      scheme: basic
    OAuth2ClientCreds:
      type: oauth2
      description: >-
        OAuth2 is a standardized protocol for authorization that allows users to
        share their private resources stored on one site with another site
        without having to provide their credentials. OAuth2 Client Credentials
        Grant workflow. This workflow is typically used for server-to-server
        interactions that require authorization to access specific resources.
      flows:
        clientCredentials:
          tokenUrl: https://account.sendcloud.com/oauth2/token/
          scopes:
            api: Default OAuth scope required to access Sendcloud API.

````