> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.alephant.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server.

# 钩子

> 管理外部事件进入艾维斯的 webhook 入口，并控制签名、范围和重放风险。

钩子用于接收外部系统事件，并触发已批准的自动化或智能体流程。它适合事件驱动集成，不适合作为未认证的通用执行入口。该入口通常只在企业版且部署已启用钩子能力后可见。

## 管理边界

| 项目 | 建议                            |
| -- | ----------------------------- |
| 入口 | 为不同业务系统创建独立 hook，避免共享一个高权限入口。 |
| 认证 | 使用签名、令牌或来源限制校验请求。             |
| 范围 | 只触发明确配置的工作流或操作。               |
| 审计 | 记录事件 ID、来源、命中规则、执行结果和失败原因。    |

## 核心概念

| 概念            | 含义                                     | 治理决策                                                       |
| ------------- | -------------------------------------- | ---------------------------------------------------------- |
| Hook point    | AIvis 流程中允许调用自定义逻辑的固定阶段。               | 将每个点视为稳定合同：先理解它何时运行、接收哪些数据，以及是否可以修改或阻断流程。                  |
| Hook          | 将某个 hook point 连接到 HTTPS endpoint 的配置。 | 每个 hook point 和环境使用一个用途明确的 endpoint，避免用宽泛转发隐藏 owner 和故障影响。 |
| Endpoint      | 接收 JSON 请求并返回预期响应的自有服务。                | 只允许批准网络访问，校验认证，并尽快返回结果。                                    |
| Fail strategy | endpoint 不可达、超时或返回无效响应时，AIvis 继续采取的行为。 | 继续执行会违反策略时使用 hard fail；hook 只做通知或观测且主流程可安全继续时使用 soft fail。 |

## 常见 Hook Points

| Hook point         | 运行时机                | 可执行动作                         | 默认取向                                    |
| ------------------ | ------------------- | ----------------------------- | --------------------------------------- |
| Document ingestion | 文档验证后、索引开始前。        | 透传内容、改写 sections，或在进入索引前拒绝文档。 | 策略执行、分类、脱敏和来源 allowlist 优先使用 hard fail。 |
| Document push      | 文档成功索引后。            | 将已索引内容通知或复制到审计日志、数据仓库或下游归档系统。 | 除非下游目标是强制合规流程，否则优先使用 soft fail。         |
| Query processing   | 用户提交查询后、进入检索或模型调用前。 | 透传查询、改写查询，或通过用户可见消息拒绝查询。      | 访问策略、数据防泄漏或受监管主题控制优先使用 hard fail。       |

具体 payload 和响应格式属于各 hook point 的合同。不要因为它们都使用 HTTP `POST`，就假设不同 hook point 接受相同字段。

## 配置前检查

* 明确事件来源、事件类型和允许触发的动作。
* 为每个 hook 设置签名校验和重放保护。
* 规划失败重试、幂等和告警策略。
* 判断哪个 hook point 可以影响主流程，哪个只用于观测或通知。
* 在连接 endpoint 前确定 fail strategy 和 timeout。
* 准备能返回合法 JSON 与 `2xx` 状态码的 endpoint。
* 将 endpoint API key 存入受管 Secret Store，并跟随所属服务轮换。

## 连接 Hook

1. 打开 AIvis 管理区域，进入 hooks 页面。
2. 选择要连接的 hook point。
3. 填写包含系统、环境和用途的显示名称。
4. 输入 HTTPS endpoint URL。生产数据不要使用公开测试 endpoint。
5. 配置认证、timeout 和 fail strategy。
6. 只有在 endpoint 通过连接测试后才保存 hook。

| 字段            | 是否必填 | 建议                                                                      |
| ------------- | ---- | ----------------------------------------------------------------------- |
| Display name  | 是    | 使用 `pii-redaction-prod` 或 `audit-export-staging` 这类名称，让日志可读。            |
| Endpoint URL  | 是    | 使用 HTTPS，并路由到负责该 hook 行为的团队拥有的服务。                                       |
| API key       | 可选   | 配置后，endpoint 必须在处理 payload 前校验传入的 `Authorization: Bearer <key>` header。 |
| Timeout       | 可选   | 设置为足够短，避免影响用户可见延迟和 worker 吞吐。                                           |
| Fail strategy | 可选   | 阻断类控制选择 hard fail；遥测或 best-effort 通知选择 soft fail。                       |

## 管理 Hooks

| 操作    | 适用时机                                                 | 变更后检查                                   |
| ----- | ---------------------------------------------------- | --------------------------------------- |
| 启用或停用 | 需要在不删除配置的情况下启动或暂停执行。                                 | 用受控事件确认预期流程行为。                          |
| 编辑    | endpoint URL、API key、timeout、名称或 fail strategy 发生变化。 | 重新执行成功、拒绝、超时和无效响应测试。                    |
| 查看日志  | hook 降级、失败或产生非预期决策。                                  | 用事件 ID 和失败原因对齐 AIvis 与 endpoint 所属服务日志。 |
| 删除    | 集成已经退役或被替换。                                          | 移除 endpoint secret，并更新所属团队 Runbook。     |

## 健康状态与失败处理

注册后持续监控 hook 健康状态。健康 endpoint 表示当前可达且近期没有执行失败；降级 endpoint 可能仍然可达，但应视为活跃的可靠性或策略风险；连接丢失表示 AIvis 无法访问 endpoint，并会按配置的 fail strategy 处理。

对于 hard-fail hooks，要测试 hook 拒绝、超时或返回无效 JSON 时用户或索引流程看到的结果。对于 soft-fail hooks，要确认主流程继续执行，同时失败仍能在日志和告警中被发现。

## 验证

* 使用合法事件验证触发路径。
* 使用无签名、错误签名和重复事件验证拒绝路径。
* 在查询历史中确认事件处理结果可追踪。
* 测试超时行为和无效 JSON 响应。
* 确认 hard-fail hooks 会阻断预期动作，soft-fail hooks 会安全继续。
* 确认 endpoint 不记录原始 secret、完整凭证或不必要的用户内容。
* 确认 request ID、event ID 和 rejection reason 能在 AIvis 日志与 endpoint 日志之间关联。

## 生产检查清单

* 每个 hook 只有一个 owner、一个环境和一个明确 hook point。
* Endpoint 通过 HTTPS、认证和网络控制限制访问。
* Endpoint 对重试和重复事件保持幂等。
* 阻断类 hooks 的用户可见或运维可见失败消息说明下一步，不泄漏策略内部细节。
* Hook 决策可审计，包括透传、改写、拒绝、超时和 endpoint failure。