Rotate a webhook endpoint's secret

POST /v1/webhooks/{id}/rotate-secret

Gives the webhook endpoint a new signing secret.

Needs webhooks:write.

Request

curl -X POST https://app.soosh.io/v1/webhooks/4c6e8a0c-2e4b-4d6f-b8a0-1c3e5a7c9e4b/rotate-secret \
  -H "Authorization: Bearer $SOOSH_API_KEY" \
  -H "Idempotency-Key: rotate-webhook-secret-example-1" \
  -H "Content-Type: application/json" \
  -d '{
    "overlap_hours": 24
  }'

const res = await fetch('https://app.soosh.io/v1/webhooks/4c6e8a0c-2e4b-4d6f-b8a0-1c3e5a7c9e4b/rotate-secret', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SOOSH_API_KEY}`,
    'Idempotency-Key': 'rotate-webhook-secret-example-1',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "overlap_hours": 24
  }),
});
console.log(await res.json());

import os
import requests

res = requests.post(
    "https://app.soosh.io/v1/webhooks/4c6e8a0c-2e4b-4d6f-b8a0-1c3e5a7c9e4b/rotate-secret",
    headers={"Authorization": f"Bearer {os.environ['SOOSH_API_KEY']}", "Idempotency-Key": "rotate-webhook-secret-example-1"},
    json={
        "overlap_hours": 24,
    },
)
print(res.json())

Response200

{
  "secret": "whsec_C2FVsBQIhrscChlQIMV+b5sSYspob7oD9uXe4RkZ1aM=",
  "previous_secret_expires_at": "2026-10-15T09:45:12.340Z"
}

Path parameters

id string · uuid

The webhook endpoint’s ID.

Body

overlap_hours integer

How long the old secret keeps signing. 0 stops it at once.

From 0 to 168. Default 24.

Headers

Idempotency-Key string

Makes this request safe to retry. See Retrying safely.

1 to 255 characters.

Switching over

The old secret keeps signing for overlap_hours. Meanwhile every request carries both signatures in webhook-signature, separated by a space, so you can switch over without missing an event.

Returns

200 The new secret, shown this once, and when the old one stops signing.

secret string

The new signing secret, shown this once.

previous_secret_expires_at string · date-time · nullable

When the old secret stops signing; null when it already has.

Errors

Besides the ones every request can get:

422invalid_fieldThe overlap_hours is outside 0 to 168.

403scope_missingThe key lacks the read scope of an event the endpoint sends.

404not_foundThere is no webhook endpoint with this ID in your workspace.

409idempotency_in_progressA request with the same Idempotency-Key is still running.

422idempotency_mismatchThe Idempotency-Key was used before for a different request, or by another of your API keys.