---
title: "Create a delivery destination"
method: POST
path: "/v1/delivery/destinations"
tags: ["Delivery"]
---

# Create a delivery destination

`POST /v1/delivery/destinations`

## Request

- Base URL: `https://api.talonic.com`
- URL: `https://api.talonic.com/v1/delivery/destinations`
- Auth: HTTP bearer

## Request body

- CreateDestinationRequest
  - `name` string, required
  - `type` string, required: Connector type. Must match a registered connector. Live types are `webhook`, `sftp`, `s3`, `azure_blob`, `google_drive`, `onedrive`, `google_sheets`.
  - `config` object: Connector-specific transport settings (e.g. `{ url, method, headers }` for `webhook`).
  - `auth_config` union: Transport credentials for the connector, discriminated by `type` (see `DestinationAuthConfig` and `/v1/delivery/catalog/connectors`). For a `webhook` destination a `signing_secret` key may also be placed here; it is stored as the destination's signing secret (encrypted, never echoed) and stripped from the credentials, so a body whose `auth_config` holds only the secret reads back as `has_auth_config: false, has_signing_secret: true`.
    - union: Destination credential payload. Write-only — server responses expose only `has_auth_config: boolean`, never the credential values themselves. The `type` field discriminates the concrete shape; valid values depend on the parent destination's connector `type` (see `/v1/delivery/catalog/connectors` for each connector's `auth_types`).
      - AuthConfigPassword: SFTP password auth.
        - `type` 'password', required
        - `password` string, required
      - AuthConfigPrivateKey: SFTP key-based auth. `passphrase` is optional.
        - `type` 'private_key', required
        - `private_key` string, required
        - `passphrase` string, nullable
      - AuthConfigAccessKey: S3 IAM access-key pair. `session_token` is optional (STS).
        - `type` 'access_key', required
        - `access_key_id` string, required
        - `secret_access_key` string, required
        - `session_token` string, nullable
      - AuthConfigConnectionString: Azure Blob Storage connection string auth.
        - `type` 'connection_string', required
        - `connection_string` string, required
      - AuthConfigAccountKey: Azure Blob Storage shared-key auth (`account_name` lives in the destination `config`).
        - `type` 'account_key', required
        - `account_key` string, required
      - AuthConfigBearer: Webhook Bearer-token auth. Emits `Authorization: Bearer {token}`.
        - `type` 'bearer', required
        - `token` string, required
      - AuthConfigBasic: Webhook HTTP Basic auth. Emits `Authorization: Basic base64(username:password)`.
        - `type` 'basic', required
        - `username` string
        - `password` string
      - AuthConfigApiKey: Webhook API-key auth. Header name defaults to `X-API-Key`.
        - `type` 'api_key', required
        - `api_key` string, required
        - `header_name` string
      - AuthConfigNone: Explicit "no authentication" marker.
        - `type` 'none', required
    - object
  - `signing_secret` string, nullable: HMAC-SHA256 secret for `webhook` destinations. Deliveries then carry `X-Talonic-Signature: t=<ms>,v1=<hex>` with `hex = HMAC(secret, "<t>.<body>")` (see the Signature verification section). Equivalent to `auth_config.signing_secret`; supplying both with different values is a 400.
  - `payload_cap_bytes` integer, nullable
  - `is_active` boolean

## Response `200`

Destination created (alias of 201).

- Destination
  - `id` string, uuid, required
  - `customer_id` string, uuid, required
  - `name` string, required
  - `type` string, required: Connector type discriminant — resolves to a registered connector. Live types are `webhook`, `sftp`, `s3`, `azure_blob`, `google_drive`, `onedrive`, `google_sheets`.
  - `config` object: Connector-specific configuration (e.g. `{ url, headers }` for webhook).
  - `has_auth_config` boolean: True when connector credentials are stored for this destination. The credential values themselves are never returned.
  - `has_signing_secret` boolean: True when an HMAC signing secret is stored. The secret itself is never returned.
  - `payload_cap_bytes` integer, nullable: Per-destination override of the TransportWrapper payload cap (bytes).
  - `is_active` boolean, required
  - `last_delivery_at` string, date-time, nullable
  - `last_delivery_status` string, nullable
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required

## Other responses

- `201`: Destination created.
- `400`: The request is invalid.
- `401`: Missing or invalid API key.
- `429`: Daily rate limit exceeded.

---

[API](https://skmtc.dev/talonic/apis/talonic-api.md) · [All operations](https://skmtc.dev/talonic/apis/talonic-api/llms.txt) · [OpenAPI document](https://skmtc.dev/talonic/apis/talonic-api/revisions/678fe5f8c9c3?raw)