Rotate webhook secret

Issue a new signing secret. The old one keeps signing for 24 hours.

POST /api/v1/webhook_endpoints/{webhook_endpoint_id}/rotate_secret

cURL

curl -X POST "https://api.wordsmith.ai/api/v1/webhook_endpoints/0e7b3c5a-9d21-4f86-b4a0-6c8e2f1d7a39/rotate_secret" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here"

Response

{
  "secret": "whsec_9b1d7a2f8e4c4f9a1c7e2b8d6a0f3e5c9b1d7a2f8e4c4f9a",
  "previous_secret_expires_at": "2026-11-10T10:00:00Z"
}

Issues a new secret, shown only in this response. Until previous_secret_expires_at, every event is signed with both secrets, so Wordsmith-Signature carries two v1 values. Accept a request if any of them matches.

​

Authentication

Requires an API key, or an OAuth token with webhooks:write.

​

Path parameters

webhook_endpoint_id · string · required

The endpoint.

​

Response

Returns the new secret and when the old one stops signing.

cURL

curl -X POST "https://api.wordsmith.ai/api/v1/webhook_endpoints/0e7b3c5a-9d21-4f86-b4a0-6c8e2f1d7a39/rotate_secret" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here"

Response

{
  "secret": "whsec_9b1d7a2f8e4c4f9a1c7e2b8d6a0f3e5c9b1d7a2f8e4c4f9a",
  "previous_secret_expires_at": "2026-11-10T10:00:00Z"
}

​

Errors

Status	error_code	When
403	aob_credential_blocked	Support staff acting on your behalf cannot see a new secret.
404	resource_not_found	No endpoint with this id that you can manage, or webhooks are not on for your organisation.