handler.register

Coming July 20, 2026

Register a customer-owned HTTPS handler to receive Cortex-dispatched triggers.

CategoryHandler
JSON-RPCtools/call
EndpointPOST /mcp

Description

Registers a handler URL for one or more action classes. Cortex HMAC-SHA256 signs every dispatched trigger with a per-handler `webhook_secret` returned on registration (store it securely — it is shown only once unless rotated). On registration, Cortex fires a one-time challenge POST that your handler must respond to with `204` within 30 seconds, proving you control the endpoint.

Input schema

FieldTypeRequiredDescription
urlstring (HTTPS URL)yesCustomer-controlled HTTPS endpoint that will receive POSTed trigger envelopes. Must be reachable from the public internet and must respond `<=30s`.
action_classesstring[]yesWhich action classes this handler accepts. Currently supported: `communicate`, `schedule`, `remind`. At least one required.
webhook_secret_aliasstringnoOptional human-readable label for the generated secret (for ops tracking). Does not affect the secret value.

Output shape

typescript
{
  handler_id: string;
  url: string;
  action_classes: string[];
  webhook_secret: string;        // shown only on creation; rotate via handler.rotate_secret
  challenge_status: "pending" | "verified";
  created_at: string;
}

Persist `webhook_secret` immediately — it cannot be retrieved later. Use `handler.rotate_secret` if you lose it. `challenge_status` is `pending` until your handler responds to the registration challenge.

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.register",
  "arguments": {
    "url": "https://handlers.your-app.com/cortex",
    "action_classes": ["communicate", "schedule"],
    "webhook_secret_alias": "prod-2026-07"
  }
}

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
{
  "handler_id": "hnd_01HXP9HANDLER",
  "url": "https://handlers.your-app.com/cortex",
  "action_classes": ["communicate", "schedule"],
  "webhook_secret": "whsec_01HXP9aBcDeFg...",
  "challenge_status": "pending",
  "created_at": "2026-05-27T14:31:00Z"
}

Errors this tool can return

CodeMeaning
invalid_argumentsTool input failed Zod validation.
unauthorizedMissing or invalid bearer token.
quota_exceededPer-minute, daily call, or daily inference budget exceeded.

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

Notes