---
title: "Rotate an event destination's signing secret"
method: POST
path: "/event-destinations/{event_destination}/rotate-secret"
tags: ["Events"]
---

# Rotate an event destination's signing secret

`POST /event-destinations/{event_destination}/rotate-secret`

## Request

- Base URL: `https://api.ekho.com`
- URL: `https://api.ekho.com/event-destinations/{event_destination}/rotate-secret`
- Auth: HTTP bearer

Mints a new signing secret and returns it in `secret`. This is the only response other than create that carries the plaintext, so store it on receipt. The outgoing secret keeps signing for `previous_secret_expires_in_seconds` (24 hours by default, 0 for an immediate cutover), and during that overlap each delivery carries one `v1=` signature per active secret, so either one verifies while you roll out the new one.

## Path parameters

- `event_destination` string, required

## Request body

- EventDestinationSecretRotate
  - `previous_secret_expires_in_seconds` integer: How long the outgoing secret keeps signing, so both secrets verify while you roll out the new one. Defaults to 86400 (24 hours). 0 retires the outgoing secret immediately; the maximum is 604800 (7 days).

## Response `200`

The signing secret was rotated.

- object
  - `data` EventDestination, required
    - `id` string, required: Typed event destination id; ids carry the `whe_` prefix.
    - `url` string, required
    - `event_types` string[], required: Every event type this destination receives.
    - `status` 'enabled' | 'disabled' | 'auto_disabled', required
    - `display_name` string, nullable, required
    - `description` string, nullable, required
    - `environment` 'dev' | 'test' | 'demo' | 'live', required: Token environment the destination was created under.
    - `api_version` string, required: API version pinned at creation.
    - `secret` string, nullable, required: The signing secret, returned only by create and rotate-secret. Store it on receipt; it is never shown again.
    - `created_at` integer, required: Epoch milliseconds the destination was created.

## Other responses

- `400`: The request was malformed or failed validation. `errors` itemizes every field at fault, so one response names them all; the fields in the example stand in for this request's own.
- `401`: Authentication is missing or invalid.
- `403`: The token lacks `webhooks:write`.
- `404`: No event destination matches that id.
- `429`: The rate limit has been exceeded.
- `500`: An unexpected error occurred.

## Changes

- **2026-09-18** `78c545d96a34`: 18 warning
  - added the new `external_id_in_use` enum value to the `code` response property for the response status `400`
  - added the new `external_id_in_use` enum value to the `code` response property for the response status `401`
  - added the new `external_id_in_use` enum value to the `code` response property for the response status `403`
  - added the new `external_id_in_use` enum value to the `code` response property for the response status `404`
  - …14 more

[Operation history](https://skmtc.dev/ekho/apis/ekho-api/changes/event-destinations/:event_destination/rotate-secret/post.md)

---

[API](https://skmtc.dev/ekho/apis/ekho-api.md) · [All operations](https://skmtc.dev/ekho/apis/ekho-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ekho/apis/ekho-api/revisions/efe485119dd7?raw)