Create Webhook
Use this when an external service (Zapier, a payment provider, a partner backend) needs to call one of an app's ops directly.
MCP name: create_webhook
Tool contract
{
"annotations": {
"destructiveHint": false,
"openWorldHint": true,
"readOnlyHint": false,
"title": "Create Webhook"
},
"description": "Use this when an external service (Zapier, a payment provider, a partner backend) needs to call one of an app's ops directly. Declares a Webhook on a declared op and returns its delivery URL, a one-time `chrm_hook_*` secret, and the op's input and output schemas, so you can hand the sender everything it needs. The sender POSTs a JSON body matching the input schema to the URL with `Authorization: Bearer <secret>` (or `?key=<secret>`) and gets the op's result back. Rejects a duplicate Webhook on the same (app, op) pair and enforces per-app / per-owner caps.",
"execution": {
"taskSupport": "forbidden"
},
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"app_id": {
"description": "The app ID (UUID) to declare a Webhook on",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
},
"name": {
"description": "A label for the owner's list; omitted means the op's own title or description",
"maxLength": 80,
"type": "string"
},
"op": {
"description": "The declared op an inbound delivery invokes",
"minLength": 1,
"type": "string"
}
},
"required": [
"app_id",
"op"
],
"type": "object"
},
"name": "create_webhook",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"advisories": {
"description": "Structured non-fatal advisories, including authoring issues and unread staff feedback responses. Each advisory.summary is also appended to the text content for the LLM path.",
"items": {
"additionalProperties": false,
"properties": {
"data": {
"additionalProperties": {},
"description": "Kind-specific structured payload. Shape varies per advisory kind.",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"doc_url": {
"description": "Optional docs pointer for this advisory kind.",
"type": "string"
},
"kind": {
"description": "Stable advisory identifier (e.g. \"legacy-bridge\").",
"type": "string"
},
"severity": {
"description": "Severity; omitted advisories are treated as 'info'.",
"enum": [
"info",
"warn"
],
"type": "string"
},
"summary": {
"description": "Agent-facing summary. Self-sufficient; no extra context required.",
"type": "string"
},
"userSummary": {
"description": "End-user-facing summary. Set when the advisory should render in-app.",
"type": "string"
}
},
"required": [
"kind",
"summary"
],
"type": "object"
},
"type": "array"
},
"ok": {
"const": true,
"description": "Indicates success. Errors arrive as content with isError:true.",
"type": "boolean"
},
"secret": {
"description": "The `chrm_hook_*` secret the sender presents. Shown once; only its hash is stored.",
"type": "string"
},
"target": {
"additionalProperties": false,
"description": "The target op's contract: the JSON body a sender must POST and the value it gets back, read from the app's active code.",
"properties": {
"input_schema": {
"anyOf": [
{
"additionalProperties": {},
"propertyNames": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
]
},
"op": {
"type": "string"
},
"output_schema": {
"anyOf": [
{
"additionalProperties": {},
"propertyNames": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
]
}
},
"required": [
"op",
"input_schema",
"output_schema"
],
"type": "object"
},
"webhook": {
"additionalProperties": false,
"properties": {
"app_id": {
"description": "UUID of the app this Webhook targets.",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"type": "string"
},
"consecutive_failures": {
"description": "Consecutive failed deliveries since the last success. Diagnostic only; nothing disables at a threshold.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"disabled_reason": {
"anyOf": [
{
"enum": [
"owner"
],
"type": "string"
},
{
"type": "null"
}
],
"description": "`owner` when disabled manually; `null` when enabled. Webhooks never auto-disable."
},
"enabled": {
"description": "`false` when the owner disabled the Webhook.",
"type": "boolean"
},
"id": {
"description": "Public Webhook id, `webhook_<uuid>` form. Use this with update_webhook/delete_webhook.",
"type": "string"
},
"last_error": {
"anyOf": [
{
"additionalProperties": false,
"properties": {
"kind": {
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"kind",
"message"
],
"type": "object"
},
{
"type": "null"
}
],
"description": "Classified failure detail from the most recent failed delivery. `null` on success or if never delivered."
},
"last_outcome": {
"description": "Result of the most recent delivery (`success`, `failure`, or `deferred`). `null` if never delivered.",
"type": [
"string",
"null"
]
},
"last_run_at": {
"description": "ISO-8601 timestamp of the most recent delivery. `null` if never delivered.",
"type": [
"string",
"null"
]
},
"name": {
"description": "The owner's label for the Webhook; defaults from the op.",
"type": "string"
},
"op": {
"description": "The declared op an inbound delivery invokes.",
"type": "string"
},
"secret_prefix": {
"description": "First characters of the secret, for matching a stored copy by eye.",
"type": "string"
},
"url": {
"description": "The delivery URL an external sender POSTs to.",
"type": "string"
}
},
"required": [
"id",
"app_id",
"op",
"name",
"url",
"secret_prefix",
"enabled",
"disabled_reason",
"last_run_at",
"last_outcome",
"last_error",
"consecutive_failures"
],
"type": "object"
}
},
"required": [
"ok",
"webhook",
"secret",
"target"
],
"type": "object"
}
}