Rotate webhook secret

Rotate a webhook's Standard Webhooks secret. Returns a shown-once whsec_<base64> secret. For 24 hours, webhook-signature carries space-separated v1,<base64> signatures from current and previous decoded keys; either verifies id.timestamp.rawBody. Required API-key scope: `webhooks_manage`; the key's owner must still be allowed to manage webhooks. A member session needs permission to manage webhooks or credentials.

POST /api/v1/workspaces/{workspaceId}/webhooks/{webhookId}/rotate

Rotate a webhook secret

cURL

curl --request POST \
  --url https://api.tetrafi.io/api/v1/workspaces/{workspaceId}/webhooks/{webhookId}/rotate \
  --header 'Authorization: Bearer <token>' \
  --header 'Idempotency-Key: <idempotency-key>'

200

{
  "secret": "<string>",
  "secretShownOnce": true
}

Authorizations

bearer_authapi_key

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Scopes

webhooks_manage · bearer_auth

webhooks_manage · api_key

Headers

X-Workspace-Id · string<uuid>

The workspace the request acts in. An API key bound to a workspace implies it: omit the header, or send that same id (another id answers 403 WORKSPACE_SCOPE_MISMATCH). A member session must send it (400 MISSING_WORKSPACE without it).

Idempotency-Key · string · required

Required for every caller (1 to 255 bytes; missing or empty is 400 IDEMPOTENCY_KEY_REQUIRED). The same key within 24 hours replays the stored 200 without rotating again: secret is null and secretShownOnce true. A new key rotates again. Reuse with a different request is 409 IDEMPOTENCY_CONFLICT.

Path Parameters

workspaceId · string · required

Workspace ID

webhookId · string · required

Webhook ID

Response

200

application/json

Secret rotated, or stored rotation replayed (secret null on replay)

Response after rotating a webhook secret: the new whsec_<base64> secret, shown once. The previous key keeps signing for 24 hours: webhook-signature then contains two space-separated v1,<base64> signatures. A Standard Webhooks verifier accepts either.

secret · string | null · required

Present only on the first response; receipts and replays contain null.

secretShownOnce · boolean · required

True even when the secret has been withheld on replay.