Destinations

A delivery destination is a configured connector instance: a connector type plus configuration and optional credentials, representing one place Talonic ships data to. Seven connectors are live, with these type values: webhook (HMAC-SHA256), sftp, s3, azure_blob, google_drive, onedrive, and google_sheets. Use Delivery → Destinations to manage them from the dashboard, or POST /v1/delivery/destinations via the API. Every destination supports a live-ping POST /v1/delivery/destinations/:id/test that exercises the full transport envelope with a tiny test payload. File-based destinations use lightweight probes (list directory, head bucket, get container properties) so the test never creates artifacts in your target storage.

Each destination stores its connector type, configuration (URL, bucket, folder path), and optional authentication credentials. Webhook destinations support HMAC-SHA256 signing via a signing secret — every payload includes a signature header so your receiver can verify authenticity. File-based destinations (S3, SFTP, Google Drive) support configurable filename templates with token substitution for binding ID, timestamp, and idempotency key.

A single destination can back multiple bindings. For example, one S3 bucket destination can receive both document.extracted and result.approved events through separate bindings, each with its own serializer and field map. This keeps your destination inventory small while supporting diverse routing requirements.

For example, to set up a webhook destination via the API: POST /v1/delivery/destinations with a body containing name, type: "webhook", config: { url: "https://ops.example.com/talonic" }, and optionally auth_config, signing_secret, and payload_cap_bytes. The response returns the destination ID, which you then reference when creating a binding. After creation, call POST /v1/delivery/destinations/:id/test to verify the connection end-to-end before routing live events to it.

For best results, always run a live-ping test after creating a destination. The test exercises the full transport envelope — SSRF validation, payload cap, and authentication — with a tiny test payload, so you catch configuration errors before real events start flowing. OAuth-based destinations (Google Drive, Google Sheets) require connecting your account first via the OAuth flow in the dashboard.

curl -X POST https://api.talonic.com/v1/delivery/destinations \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Data Lake S3",
    "type": "s3",
    "config": {
      "bucket": "talonic-exports",
      "region": "us-east-1",
      "prefix": "extractions/{date}/"
    },
    "auth_config": {
      "type": "access_key",
      "access_key_id": "AKIA...",
      "secret_access_key": "..."
    }
  }'

# Test the connection (HeadBucket probe, no objects written):
curl -X POST https://api.talonic.com/v1/delivery/destinations/dest_s3/test \
  -H "Authorization: Bearer $TALONIC_API_KEY"
# -> { "success": true, "durationMs": 89, "message": "bucket 'talonic-exports' reachable" }

File-based destinations (S3, SFTP, Google Drive, OneDrive, Azure Blob) support configurable filename templates with token substitution. Available tokens include {binding_id}, {event_id}, {customer_id}, {idempotency_key}, {attempt}, {timestamp_iso}, {date}, and {deliverable_type}. For example, a template like extractions/{date}/{deliverable_type}_{event_id}.json produces filenames like extractions/2025-04-22/notification_12345.json. Path traversal tokens (..) are automatically stripped for security. The idempotency key is embedded in the filename for SFTP and OneDrive destinations since these protocols do not support object metadata.

Deleting a destination orphans its bindings rather than deleting them. Each binding that pointed at the destination is deactivated, its last_status is set to destination_deleted, and its destination_id becomes null. The binding keeps its signal filter, serializer, field map, and retry policy, so nothing about the routing rule is lost. To bring it back, update the binding with a new destination_id; that re-points it and switches it back on. A binding update that would leave an orphaned binding without a destination is rejected, and any delivery attempted through an orphaned binding fails with destination_missing.