Create Destination

Creates an event destination. Returns destination details and a signing secret for verifying event payloads.

POST /destinations

This endpoint creates an event destination to receive Stedi events at a specific URL. You can create up to 16 event destinations per Stedi account.

1. Call this endpoint with the destination name, event types you want to receive, and the destination URL where you want to receive events.
2. Stedi creates the destination.
3. The endpoint returns the destination details, including a signing secret that you can use to verify the authenticity of event payloads. Store the signing secret securely.

You can review and manage all destinations you create through this endpoint on the Event Destinations page.

Authorizations

Authorization · Required Header

A Stedi API Key for authentication. Supports both test and production API keys.

Headers

Idempotency-Key · String Length : 1 - 255

A unique string to identify this request to the server. If not set, Stedi generates one automatically.

The key can be up to 255 characters. You can safely retry requests with the same idempotency key within 24 hours of making the first request. This prevents duplicate operations due to network errors or other intermittent failures. Learn more.

Body

application/json

concurrencyLimit · Number Range : ≥ 1

Maximum concurrent deliveries for this destination. If not set, Stedi applies your account default (typically 5). Stedi rejects requests exceeding your account maximum (typically 20) with a 400 error. Contact Stedi to change your limits.

description · String Max length : 1024

A description of the destination's purpose, such as "Receives transaction enrollment task notifications."

destinationUrl · String Required Regex pattern : ^https://.+$

The URL where you want Stedi to deliver payloads through HTTP POST.

eventTypes · Array of Strings Required Min items : 1

The event types you want Stedi to send to this destination. Visit event types for a complete list.

name · String Required Length : 1 - 255

A human-readable name for the destination. Stedi displays this name in the portal.

status · String

The destination's status upon creation. Default is ENABLED.

Possible values

ENABLED

DISABLED

Response

application/json

concurrencyLimit · Number Range : ≥ 1

The maximum number of concurrent deliveries for this destination. Contact Stedi to change your account limits.

createdAt · String Required Format : date-time

Creation timestamp for this destination.

description · String Required Max length : 1024

A description of the destination's purpose, such as "Receives transaction enrollment task notifications."

destinationUrl · String Required Regex pattern : ^https://.+$

The URL where Stedi delivers payloads through HTTP POST.

eventTypes · Array of Strings Required Min items : 1

The event types Stedi sends to this destination. Visit event types for a complete list.

id · String Required Regex pattern : ^[a-z]{3,5}_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

The unique identifier for the destination.

lastDeliveryTime · String Format : date-time

The timestamp for Stedi's most recent delivery attempt to this destination. Absent when Stedi hasn't yet attempted a delivery.

name · String Required Length : 1 - 255

A human-readable name for the destination. Stedi displays this name in the portal.

signingSecret · String Required Regex pattern : ^whsec_[A-Za-z0-9+/=]+$ Format : password Length : 30 - 255

The signing secret for verifying event payloads. Store it securely. Visit verify event signatures for details.

status · String Required

The destination's current status. Stedi only sends event payloads to ENABLED destinations.

Possible values

ENABLED

DISABLED

updatedAt · String Required Format : date-time

Last update timestamp for this destination.

Request

curl --request POST \
  --url "https://events.us.stedi.com/2026-02-01/destinations" \
  --header "Idempotency-Key: a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  --header "Authorization: <api_key>" \
  --header "Content-Type: application/json" \
  --data '{
    "destinationUrl": "https://example.com/webhooks",
    "eventTypes": [
      "enrollment.activated"
    ],
    "name": "My Destination",
    "status": "ENABLED"
  }'

Response

{
  "createdAt": "2026-02-01T12:00:00Z",
  "description": "Receives enrollment notifications",
  "destinationUrl": "https://example.com/webhooks",
  "eventTypes": [
    "enrollment.activated"
  ],
  "id": "dst_550e8400-e29b-41d4-a716-446655440000",
  "name": "My Destination",
  "signingSecret": "whsec_YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXoxMjM0NTY=",
  "status": "ENABLED",
  "updatedAt": "2026-02-01T12:00:00Z"
}