Configure and test event destinations

You can configure event destinations that automatically send Stedi events to your endpoint. Events indicate changes to Stedi resources, such as transaction enrollment requests.

In each event message, Stedi includes a signature you can use to verify its authenticity. Stedi also automatically manages retries for event deliveries and sends you in-app notifications and emails when event deliveries fail repeatedly. You can manage your notification preferences to control which notifications you receive.

Event destination endpoints are available in the Stedi TypeScript and Python SDKs. Visit SDKs for installation and usage details.

Create event destinations

You can create up to 16 event destinations per Stedi account. You can create event destinations through the API or manually through the Stedi portal.

API

Call the Create Event Destination endpoint with the destination name, webhook URL, and event types you want to receive.

For example, the following request creates a destination named "My Destination" that subscribes to enrollment.activated events and delivers them to https://example.com/webhooks:

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"
  }'

The API returns the destination details and the signing secret:

{
  "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"
}

Store the signing secret securely – you'll need it to verify that events you receive are from Stedi.

Stedi portal

To create a destination in the portal:

1. Go to the Event destinations page in your developer settings.

2. Click All event destinations.

3. Click + New destination.

4. Enter the following information into the Create an event destination form:

   1. Name: Choose a descriptive, human-readable name for the event destination. Stedi displays this name in the portal for identification.

   2. URL: Enter the webhook URL where you want Stedi to send events. The URL must use https:// and must point directly at your webhook receiver. Stedi doesn't follow HTTP redirects - if your endpoint responds with a 3xx status code, Stedi records the delivery as a failure.

   3. Description: Optionally, describe the intended use for the destination in more detail. Stedi displays this description in the portal.

   4. Events: Select the event types you want to send to the designated webhook URL.

5. Click Create destination. Stedi displays a modal containing the signing secret for this webhook. Save it to a secure location. You need it to verify that the events you receive are from Stedi.

You can now begin testing the event destination.

Trigger test events

You can manually trigger event.ping events for any configured event destination. To trigger test events:

1. Go to the Event destinations page in your developer settings.
2. Click the event destination you want to test.
3. Click the Event deliveries tab.
4. Click the Ping button.

Stedi attempts to deliver an event.ping to the designated webhook URL. You can review its status and details on the Event deliveries tab.

Secrets

Stedi generates a secret for each event destination. You can use the secret to verify the authenticity of the event messages you receive from Stedi.

Retrieve secrets

You can retrieve an event destination's secret through the API or manually through the Stedi portal.

API

Call the Get Event Destination Secret endpoint with the destination ID.

For example, the following request retrieves the signing secret for the specified destination:

curl --request GET \
  --url "https://events.us.stedi.com/2026-02-01/destinations/{destinationId}/secret" \
  --header "Authorization: <api_key>"

The API returns the signing secret:

{
  "signingSecret": "whsec_YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXoxMjM0NTY="
}

Stedi portal

You can review and copy an event destination's secret at any time from its Overview tab on the Event destinations page in your developer settings.

Rotate secrets

You can rotate the secret in accordance with your organization's security policies. You can rotate secrets through the API or manually through the Stedi portal.

When you rotate a secret, you can specify an expiry period for the previous secret. If you specify an expiry period, the event message contains two signatures until that period concludes: one matching the previous secret and one matching the new secret. You'll need to run any verification steps with both until the expiry period ends.

Each event destination can have only two active secrets at a time. If you set an expiry period for the rotated secret, you must wait until that expiry period has passed before attempting to rotate the secret again.

API

Call the Rotate Event Destination Secret endpoint with the destination ID and optionally specify how long the previous secret remains valid (default is 24 hours).

For example, the following request rotates the secret for the specified destination with a 24-hour grace period:

curl --request POST \
  --url "https://events.us.stedi.com/2026-02-01/destinations/{destinationId}/secret/rotate" \
  --header "Idempotency-Key: d4e5f6a7-b8c9-0123-defa-234567890123" \
  --header "Authorization: <api_key>" \
  --header "Content-Type: application/json" \
  --data '{
    "previousSecretExpiryHours": 24
  }'

The API returns the new signing secret and the expiration time for the previous secret:

{
  "previousSecretExpiresAt": "2025-01-01T00:00:00Z",
  "signingSecret": "whsec_bmV3c2VjcmV0Zm9ycm90YXRpb25leGFtcGxlMTIzNA=="
}

Stedi portal

To rotate a secret in the portal:

1. Go to the Event destinations page in your developer settings.
2. Click the event destination you want to edit to go to its Overview tab.
3. Under Signing secret, click the Rotate secret icon.
4. Select an Expiry period. This is the number of hours the previous secret remains valid after rotation. Available options are:
   • 0 hours (previous secret expires immediately)
   • 24 hours
   • 720 hours (30 days)
5. Click Rotate.

Manage event destinations

Manage event destinations using the API or Stedi portal.

API

You can manage event destinations programmatically through the API. Visit the following API reference pages for more information:

• List Event Destinations
• Get Event Destination
• Update Event Destination
• Delete Event Destination

Stedi portal

You can review a list of all configured event destinations from the Event destinations page in your developer settings.

Click the ellipses (...) to the right of any destination to view, edit, disable, re-enable, or delete it.

Disable versus delete

Disabling an event destination causes Stedi to stop sending new events to the webhook. Stedi also attempts to complete any in-progress retry attempts, and then pauses additional retries until the event destination is re-enabled. Once you re-enable the event destination, Stedi resumes retrying undelivered events until it reaches the retry limit.

Deleting an event destination stops all event deliveries, including in-progress retry attempts immediately.