handler.rotate_secret

Coming July 20, 2026

Rotate the HMAC signing secret for a registered handler.

CategoryHandler
JSON-RPCtools/call
EndpointPOST /mcp

Description

Generates a new `webhook_secret` and returns it once. There is a 60-second overlap window during which both the old and new secrets verify, so your handler can roll without dropping in-flight triggers. Outside the window only the new secret verifies.

Input schema

FieldTypeRequiredDescription
handler_idstringyesHandler to rotate.

Output shape

typescript
{
  ok: boolean;
  webhook_secret: string;
  rotated_at: string;
  overlap_expires_at: string;
}

Example call

JSON-RPC tools/call request body (omit the JSON-RPC envelope when using an SDK; the SDK adds it for you):

jsontools/call params
{
  "name": "handler.rotate_secret",
  "arguments": { "handler_id": "hnd_01HXP9HANDLER" }
}

Example response

Tool results are always wrapped as content[0].text with a stringified JSON body. The shape below is what you get back from JSON.parse(result.content[0].text):

jsonparsed result body
{
  "ok": true,
  "webhook_secret": "whsec_01HXP9zYxWvUt...",
  "rotated_at": "2026-05-27T15:31:00Z",
  "overlap_expires_at": "2026-05-27T15:32:00Z"
}

Errors this tool can return

CodeMeaning
invalid_argumentsTool input failed Zod validation.
unauthorizedMissing or invalid bearer token.

See the full error catalog for resolution steps on each code, plus the standard transport-layer responses (401, 429).

Notes