Skip to main content
Glama
Sign In
Kiln

Kiln

by codeofaxel
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python

register_webhook

Destructive

Register an HTTPS endpoint to receive Kiln event notifications, optionally filtering events and securing payloads with HMAC-SHA256.

Instructions

Register a webhook endpoint to receive Kiln event notifications.

Args:
    url: The HTTPS URL that will receive POST requests with event payloads.
    events: Optional list of event types to subscribe to (e.g.
        ["job.completed", "print.failed"]).  If omitted, all events are sent.
    secret: Optional shared secret for HMAC-SHA256 payload signing.
    description: Human-readable label for this endpoint.

Returns the registered endpoint ID.  Use ``list_webhooks`` to see all
endpoints and ``delete_webhook`` to remove one.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "url": "<url>"
    },
    "name": "register_webhook"
  }
}

Input Schema

NameRequiredDescriptionDefault
urlYesThe HTTPS URL that will receive POST requests with event payloads.
eventsNoOptional list of event types to subscribe to (e.g. ["job.completed", "print.failed"]). If omitted, all events are sent.
secretNoOptional shared secret for HMAC-SHA256 payload signing.
descriptionNoHuman-readable label for this endpoint. Default: "".

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv1.5.1
    • changedInput schema / properties / description / description
      Previous value: -"Default: \"\"."New value: +"Human-readable label for this endpoint. Default: \"\"."
    • addedInput schema / properties / events / description
      Added value: +"Optional list of event types to subscribe to (e.g. [\"job.completed\", \"print.failed\"]).  If omitted, all events are sent."
    • addedInput schema / properties / secret / description
      Added value: +"Optional shared secret for HMAC-SHA256 payload signing."
    • addedInput schema / properties / url / description
      Added value: +"The HTTPS URL that will receive POST requests with event payloads."
  2. Changed4 schema fields changedv1.5.0
    • removedInput schema / properties / description / default
      Removed value: -""
    • addedInput schema / properties / description / description
      Added value: +"Default: \"\"."
    • removedInput schema / properties / events / default
      Removed value: -null
    • removedInput schema / properties / secret / default
      Removed value: -null
  3. First observedv0.1.0

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already flag this as a non-read-only, open-world, destructive operation; the description adds meaningful behavior beyond that: HTTPS-only delivery via POST, HMAC-SHA256 signing with the secret, and default subscribe-to-all when events is omitted. However it never addresses the destructiveHint=true annotation — nothing explains what gets overwritten or what happens if the same URL is registered twice — leaving the most consequential behavior unexplained.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the action in the first sentence, then Args, then return value and sibling pointers — a clean, scannable order. The Args section duplicates the input schema nearly word-for-word, which is the main wasted text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

It documents the return value ("Returns the registered endpoint ID") which compensates for the absent output schema, and routes to siblings. But for a destructive, open-world registration with no output schema, an agent still lacks idempotency/duplicate behavior, what event types exist, and error conditions.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the Args block largely restates the schema descriptions verbatim (URL meaning, events default, secret signing, label). The event-name examples and the "if omitted, all events are sent" default are useful semantics but are already present in the schema, so the description adds little beyond it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Register a webhook endpoint") plus the payload purpose ("receive Kiln event notifications"), and names the two sibling tools that cover the adjacent operations, so an agent can distinguish it from list_webhooks/delete_webhook without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Routing guidance is explicit for the adjacent operations ("Use list_webhooks to see all endpoints and delete_webhook to remove one"), which is real when-to-use-which signal. What's missing is guidance on when registration itself is appropriate (e.g., duplicates, re-registering an existing URL) or prerequisites such as auth/HTTPS validation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools