Rotate Tool Webhook Secret | SpeechifyAI API

{
  "id": "tool_01kb9kefcacry5t3662gfsgtzj",
  "name": "Example name",
  "description": "Example description.",
  "kind": "builtin",
  "config": {
    "fire_and_forget": false,
    "headers": {
      "key": "example"
    },
    "method": "POST",
    "params": [
      {
        "description": "Example description.",
        "name": "Example name",
        "required": true,
        "type": "string"
      }
    ],
    "timeout_ms": 5000,
    "url": "https://example.com/webhook"
  },
  "created_at": "2026-06-24T18:03:11Z",
  "updated_at": "2026-06-24T18:03:11Z",
  "webhook_secret": "whsec_01jqr8x9zg5k2m3n4p5q6r7s8t"
}

Rotate the HMAC signing secret on a webhook tool. The tool id is preserved so attached agents keep working; only the secret rolls. The new plaintext is returned on webhook_secret exactly once — store it immediately, subsequent reads always return the masked placeholder. The previous secret is invalidated immediately on success.

Authentication

AuthorizationBearer

Enter your API key with the Bearer prefix, e.g. ‘Bearer sk_…’.

Path parameters

tool_definition_idstringRequired

Tool definition id (prefixed external id, tool_...).

Response headers

X-Request-IDstring

Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends an X-Request-ID request header the server echoes it back (sanitized and length-capped) so one logical request can be traced end-to-end; otherwise the server generates a fresh value. Log it on every response and quote it in support requests - it is the stable handle that ties your observation to Speechify’s server-side logs, and it matches the request_id field in the error envelope.

Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends an `X-Request-ID` request header the server echoes it back (sanitized and length-capped) so one logical request can be traced end-to-end; otherwise the server generates a fresh value. Log it on every response and quote it in support requests - it is the stable handle that ties your observation to Speechify's server-side logs, and it matches the `request_id` field in the error envelope.

Response

The tool with its newly-rotated webhook_secret.

idstringformat: "^tool_[0-9a-hjkmnp-tv-z]{26}$"

Prefixed wire identifier (tool_<26 char Crockford base32>).

namestring

descriptionstring

kindenum

What kind of tool this is, and where it executes.

builtin: a worker-resident platform capability (e.g. end_call, play_audio), configured per-agent
webhook: worker signs a payload and POSTs it to your URL
client: worker dispatches to the caller’s browser/SDK via data channel
mcp: worker connects to a customer-hosted MCP server and proxies tool calls

configobject

One of WebhookToolConfig, ClientToolConfig, or MCPToolConfig depending on kind.

created_atdatetime

updated_atdatetime

webhook_secretstring

HMAC signing secret for kind=webhook. Returned in full only on the create response; all subsequent reads return a masked placeholder. Store it on first create — there is no way to retrieve it later.

Errors

400

Bad Request Error

401

Unauthorized Error

404

Not Found Error

$	curl -X POST https://api.speechify.ai/v1/agents/tool-definitions/tool_01jqr8x9zg5k2m3n4p5q6r7s8t/rotate-secret \
>	-H "Authorization: Bearer <token>"

Authentication

Path parameters

Headers

Response headers

Response

Errors