<a id="webhook-operations"></a>

# `webhook` 操作

<!-- i18n: source=docs/reference/operations/webhook.md blob=8fe85868279336302f0f597903d202ca2dcf6179 model=claude-sonnet-5-5 -->
> 本页由机器从[英文原文](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations/webhook.md)翻译，内容以英文原文为准。
> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations/webhook.md), which is authoritative.


每个 `webhook.*` 操作接受和返回的确切字段。

<!-- Generated by `python scripts/codegen/docs_reference.py` from the op registry; edit the models, not this page. -->

每个操作都是通过 HTTP 的 `POST /v1/<op>`，同时也是 MCP 工具 `loom_<op>`。身份字段（`org`、`namespace`、`agent`、`user_id`、`session_id`）会在传输层能够提供时，根据令牌和 MCP 会话自动填充；对于单用户服务器上不带令牌的 HTTP 调用，除 `code.*` 和 `tracker.*`（它们沿用各自平面的设置）外，所有操作都使用该安装的 org，而在[部分操作](https://github.com/ClickHouse/loom/blob/main/docs/reference/http-api.md#request)上，其命名空间和 agent 也会如此填充；参见[身份与命名空间](/zh-CN/concepts/identities-and-namespaces)。[操作索引](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md)说明了角色、种类以及 MCP 的 `all` 列表。未知的输入字段仍会被处理，并列在 `ignored_args` 中。

<!-- prettier-ignore-start -->

<a id="webhookdeliveries"></a>

## `webhook.deliveries`

该命名空间最近 3 天的 webhook 事件及其投递状态。

`POST /v1/webhook.deliveries` · MCP `loom_webhook_deliveries` · 角色 `admin` · 幂等 · 不在 MCP `all` 工具集中列出

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该操作读取或写入的命名空间。 |
| `webhook_id` | `str` | `''` | 仅返回该 webhook 的事件；"" 表示该命名空间的所有 webhook。 |
| `status` | `Literal['pending', 'delivered', 'dead'] \| None` | `None` | 仅返回处于该状态的事件；None 表示所有状态。 |
| `limit` | `int` | `100` | 最多返回这么多事件，按最新优先，范围 1-500。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `deliveries` | `list[WebhookDelivery]` | 事件，按最新优先。 |

<a id="webhooklist"></a>

## `webhook.list`

该命名空间的记忆 webhook。

`POST /v1/webhook.list` · MCP `loom_webhook_list` · 角色 `admin` · 幂等 · 不在 MCP `all` 工具集中列出

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该操作读取或写入的命名空间。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `webhooks` | `list[WebhookInfo]` | 该命名空间当前有效的注册，按最早优先。 |

<a id="webhookregister"></a>

## `webhook.register`

注册一个 URL，当该命名空间中的记忆发生变化时通知它。

`POST /v1/webhook.register` · MCP `loom_webhook_register` · 角色 `admin` · 幂等 · 已审计 · 不在 MCP `all` 工具集中列出

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该操作读取或写入的命名空间。 |
| `url` | `str` | 必填 | 事件 POST 的目标地址：一个 https URL（仅在部署允许时可用 http），其主机名须解析为公网地址。 |
| `secret_ref` | `str` | 必填 | 保存签名密钥的环境变量名（不是密钥本身）：`LOOM_WEBHOOK_SECRET_<ORG>__<NAME>`，其中 ORG 为转为大写的 org id，a-z 和 0-9 之外的每个字节写作 `_` 加两位十六进制数字。 |
| `events` | `list[Literal['memory.written', 'memory.revised', 'memory.tombstoned', 'memory.restored', 'memory.redacted', 'memory.erased']]` | *(计算得出)* | 要发送的事件类型；默认为全部。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `webhook` | `WebhookInfo` | 已存储的注册信息。 |

<a id="webhookremove"></a>

## `webhook.remove`

删除一个记忆 webhook；调用之后不再发送它的任何事件，已在进行中的 POST 除外。

`POST /v1/webhook.remove` · MCP `loom_webhook_remove` · 角色 `admin` · 幂等 · 已审计 · 不在 MCP `all` 工具集中列出

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str` | 必填 | 该操作读取或写入的命名空间。 |
| `webhook_id` | `str` | 必填 | webhook.register 或 webhook.list 返回的 webhook_id。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `removed` | `bool` | 当该命名空间中没有具有该 id 的有效 webhook 时为 False。 |

<!-- prettier-ignore-end -->
