handler.delete

Coming July 20, 2026

Deregister a handler. Preserves delivery history; revokes the webhook secret.

CategoryHandler
JSON-RPCtools/call
EndpointPOST /mcp

Description

Removes the handler from the dispatch routing table. Past delivery history is preserved (and queryable via `trigger.history`) for audit purposes. The `webhook_secret` is immediately revoked; in-flight retries to a deleted handler short-circuit to the DLQ.

Input schema

FieldTypeRequiredDescription
handler_idstringyesHandler to delete.

Output shape

typescript
{ ok: boolean; deleted_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.delete",
  "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, "deleted_at": "2026-05-27T15:30: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