Events

Rotate an event destination's signing secret

Changed on Sep 18, 2026

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.

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

Path parameters

event_destinationstring required

Example:whe_a1b2c3d4e5f6

Request body

previous_secret_expires_in_secondsinteger

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).

Example request

{
  "previous_secret_expires_in_seconds": 3600
}

Response

The signing secret was rotated.

Example response

{
  "data": {
    "id": "whe_a1b2c3d4e5f6",
    "api_version": "v1",
    "secret": "whsec_4f1d…"
  }
}

Changes

Sep 18, 202678c545d96a34 Revision changes
- warning
  added the new external_id_in_use enum value to the response property for the response status
- warning
  added the new external_id_in_use enum value to the response property for the response status
- warning
  added the new external_id_in_use enum value to the response property for the response status
- warning
  added the new external_id_in_use enum value to the response property for the response status
- warning
  added the new external_id_in_use enum value to the response property for the response status
- warning
  added the new external_id_in_use enum value to the response property for the response status
- warning
  added the new requires_ekho_review enum value to the response property for the response status
- warning
  added the new requires_ekho_review enum value to the response property for the response status
- warning
  added the new requires_ekho_review enum value to the response property for the response status
- warning
  added the new requires_ekho_review enum value to the response property for the response status
- warning
  added the new requires_ekho_review enum value to the response property for the response status
- warning
  added the new requires_ekho_review enum value to the response property for the response status
- warning
  added the new resource_not_writable enum value to the response property for the response status
- warning
  added the new resource_not_writable enum value to the response property for the response status
- warning
  added the new resource_not_writable enum value to the response property for the response status
- warning
  added the new resource_not_writable enum value to the response property for the response status
- warning
  added the new resource_not_writable enum value to the response property for the response status
- warning
  added the new resource_not_writable enum value to the response property for the response status

Operation history