Rotate Destination Secret

Rotates the signing secret for a destination. The previous secret remains valid for the period specified by `previousSecretExpiryHours` (or `0` for immediate invalidation) to allow for a graceful transition.

POST /destinations/{destinationId}/secret/rotate

This endpoint rotates the signing secret for an event destination. Secret rotation is an important security practice that helps protect your event delivery endpoint.

1. Call this endpoint with the destination's ID and optionally specify how long the previous secret remains valid (default is 24 hours).
2. Stedi generates a new signing secret.
3. The endpoint returns the new secret and the expiration time for the previous secret.

The previous secret remains valid for the grace period you specify, allowing you to update your application to use the new secret without disrupting event delivery. During this time, we recommend verifying event signatures using both the old and new secrets.

You cannot rotate a secret again while a previous rotation's grace period is still active. Wait until the time specified in previousSecretExpiresAt before rotating again.

Authorizations

Authorization · Required Header

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

Path Parameters

destinationId · String 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. You can retrieve destination IDs with the List Destinations endpoint.

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

previousSecretExpiryHours · Number Range : ≥ 0 and ≤ 720

The number of hours you want the previous secret to remain valid after rotation.

• Default is 24 hours.
• Set to 0 when you want the previous secret to expire immediately — in-flight payloads signed with the previous secret fail verification.
• You can't rotate again until this grace period expires.

Response

application/json

previousSecretExpiresAt · String Format : date-time

Expiration timestamp for the secret this rotation replaced. Equals the rotation time when you set previousSecretExpiryHours to 0. You can't rotate again until this timestamp passes.

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

The new signing secret for verifying event payloads. Visit verify event signatures for details.

Request

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

Response

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