Skip to main content

Create Destination

Create a delivery destination with connector type, transport config, and authentication. Supported types: webhook, sftp, s3, azure_blob, google_drive, onedrive.

Create a new delivery destination by specifying the connector type, transport configuration, and optional authentication. The config and auth_config schemas vary by destination type — see the catalog endpoint for connector capabilities.

The typical workflow is: create a destination first, then create one or more bindings that route signals to it. Call GET /v1/delivery/catalog/connectors to see which connector types are available and what config and auth_config schemas each expects.

The response returns the created destination with is_active: true and last_delivery_at: null. Auth credentials are never echoed back — use the has_auth_config and has_signing_secret booleans to confirm they were stored. After creation, use POST /v1/delivery/destinations/:id/test to verify connectivity before setting up bindings.

For webhook destinations, include a signing_secret in auth_config to enable HMAC-SHA256 request signing. For file-drop destinations (S3, SFTP, Azure Blob), set payload_cap_bytes if you need to override the global 5 MiB cap. OAuth destinations (Google Drive, OneDrive) require completing the OAuth flow first.

OAuth-based destinations (google_drive, onedrive) require completing an OAuth flow before creating the destination. Use the OAuth start endpoint to initiate the flow and obtain tokens.
POST/v1/delivery/destinations

Response

Response fields (201 Created)

idstringDestination UUID.
namestringDestination name.
typestringConnector type.
configobjectTransport config. Auth credentials are never echoed back.
has_auth_configbooleanWhether auth credentials are configured.
has_signing_secretbooleanWhether an HMAC signing secret is configured.
payload_cap_bytesinteger | nullPer-destination payload cap override in bytes.
is_activebooleanAlways true on creation.
last_delivery_atnullAlways null on creation.
last_delivery_statusnullAlways null on creation.
created_atstringISO 8601 creation timestamp.
updated_atstringISO 8601 last update timestamp.

Response (201 Created)

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Production Webhook",
  "type": "webhook",
  "config": { "url": "https://api.example.com/ingest", "headers": { "X-Source": "talonic" } },
  "has_auth_config": false,
  "has_signing_secret": true,
  "payload_cap_bytes": null,
  "is_active": true,
  "last_delivery_at": null,
  "last_delivery_status": null,
  "created_at": "2024-09-01T10:00:00.000Z",
  "updated_at": "2024-09-01T10:00:00.000Z"
}

Errors

Error responses

400validation_errorInvalid destination configuration for the chosen connector type.
401unauthorizedMissing or invalid API key.
429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

Related

List Destinations
Test Destination