Finx
点金文档中心
查看 Markdown

事件投递

通过 Webhook 让点金平台在关键事件发生时主动回调你的服务，实现外部审计、风险拦截或系统联动。

什么是 Webhook

Webhook 是点金平台主动调用外部 HTTP 接口的回调机制。当某个关键事件（如收到用户消息、工具调用前后、智能体执行完毕等）在平台内发生时，平台会按你配置的地址发起 POST 请求，把事件上下文以 JSON 投递给你的服务。

维度说明
触发方点金平台主动调用（不是你定时拉取）
协议HTTP(S) POST + JSON Body（生产建议 HTTPS）
鉴权可选：X-Webhook-Signature HMAC 签名 + X-Webhook-Timestamp 时间戳，用于防伪造与防重放
失败策略拦截型可配 ALLOW（失败放行主流程）或 DENY（失败终止主流程）
配置粒度两个配置面：应用空间 Webhook（挂载到指定 Agent 生效，首推）+ 租户设置「事件管理」（启用后对租户内全部 Agent 生效）；命中同一事件时合并后按 hookOrder 升序执行

典型用途： 敏感词审核 · 危险工具调用拦截 · 调用链路审计 · Token 消耗实时上报 · 与外部 IM / 工单系统联动。

事件类型

按"是否挂起主流程"的标准，划分为两类，共 8 种事件：

拦截型（3 个，可改写或拒绝执行，会阻塞主流程等待回调返回）

事件触发时机
user_message收到用户消息时 — 可审核敏感词、改写输入或直接拒绝
pre_tool_use工具调用前 — 可拦截危险调用或修改参数
pre_scheduled_task定时任务执行前 — 可拦截或调整执行参数

观察型（5 个，仅通知不阻断，平台异步投递不等待）

事件触发时机
post_tool_use工具调用完成后 — 用于审计、耗时监控
session_start会话创建或恢复时
agent_completion智能体整轮执行结束 — 含成功 / 失败信息
post_llm_callLLM 每次推理完成 — 记录 Token 消耗
post_scheduled_task定时任务执行完毕 — 用于结果上报

优先选观察型。 拦截型 Hook 处于主流程关键路径，回调超时或返回 5xx 会直接影响用户体验；只在确实需要"修改 / 拒绝"输入时才使用。

在哪里配置

控制台提供两个配置面：在「应用空间」中配置的 Webhook 通过挂载到指定智能体生效；在「租户设置」中配置的 Hook 启用后对租户内全部 Agent 生效。两个配置面分别兼顾灵活性（按 Agent 精准挂载）与便捷性（全局一键生效）。

配置面入口说明
应用空间 Webhook应用空间侧边栏 → 「Webhook」在当前应用下创建 Webhook；创建后需在智能体详情中挂载生效
挂载到智能体应用空间 → 智能体 → Agent 详情 → 「Webhook（已挂载 N）」卡片 → 「管理」勾选需要在该智能体运行时生效的 Webhook，保存时以选中项全量覆盖
租户设置事件管理租户设置 → 「事件管理」创建并启用 Hook，启用后对租户内全部 Agent 生效；可设执行顺序（hookOrder，数值越小越先执行）

两处的编辑页均提供「DryRun 调试」面板（不入库直接试投递）。若只想对个别 Agent 生效，请使用下方的 Agent 级挂载。

Agent 级挂载

应用空间 Webhook 背后是一套「无状态 Webhook 注册表 + Agent 挂载」的两层解耦模型：先在注册表登记 Webhook 配置，再把配置精准挂载到需要的 Agent 上，配置与生效范围互相独立。

层作用控制台入口
Webhook 注册表管理 Webhook 配置本体（名称 / 事件 / 回调地址 / 签名等）；仅登记不生效应用空间侧边栏 → 「Webhook」（页面「Webhook 管理」）
Agent 挂载把注册表中的配置挂载到指定 Agent，挂载后才参与该 Agent 的事件投递Agent 详情 → 「Webhook（已挂载 N）」卡片 → 「管理」（保存时以选中项全量覆盖）

应用级 Webhook 没有独立的启停开关：挂载即生效、取消挂载即失效。

运行时合并规则：

  • 租户级 Hook 与 Agent 挂载的 Webhook 会合并为一个执行列表，按 hookOrder 统一升序执行。
  • Agent 挂载独立生效：即使租户未配置任何租户级 Hook，挂载到 Agent 的 Webhook 同样会被触发。
  • 拦截型事件中任一 Hook 返回拒绝即短路，后续 Hook 不再执行。

推荐用法： 首推在应用空间配置 Webhook 并挂载到目标 Agent；确需全局生效的事件（如审计）可在租户设置的事件管理中配置；不推荐在租户级配置拦截型 Hook，失败或拒绝会阻断租户内所有 Agent 的执行。

如何配置

以下以租户设置 → 事件管理为例；应用空间 Webhook 的创建流程与之类似，创建后需在智能体详情中挂载生效。

接入流程： 进入事件管理 → 创建 Hook → 选执行时机 → 填回调地址 → DryRun 调试 → 启用

1
进入事件管理
登录租户控制台后，进入「租户设置 → 事件管理」，即可看到当前租户下的全部 Hook。

打开事件管理 →

2
点击「创建 Hook」
在列表页右上角点击「创建 Hook」按钮，弹出创建表单。

如果是首次接入，建议先创建一个观察型 Hook（如 agent_completion）跑通链路，再逐步替换为拦截型。

3
填写表单四要素
名称 / 执行时机 / 回调地址 / 失败策略
字段必填说明
名称是业务可读的名称，如「用户消息审核」
执行时机是8 种事件中多选 N 种；同一 Hook 可同时订阅多个事件
回调地址是你的服务接收事件的 URL（http:// 或 https:// 开头，生产建议 HTTPS），平台以 POST + JSON 投递
失败策略拦截型必填ALLOW（回调失败时放行主流程）或 DENY（直接终止）
签名密钥否推荐填写；平台会用此密钥对请求体计算 HMAC，放在 X-Webhook-Signature 头中
超时否拦截型默认 3000ms，观察型默认 5000ms；超过即按失败策略处理

高级配置（可选字段）

字段说明
toolNameMatch工具名过滤，仅对 pre_tool_use / post_tool_use 生效，默认 *。四种写法：* 或留空 = 全部工具；/正则/（斜杠包裹）= 正则匹配；a|b = 管道分隔枚举，命中其一即匹配；其余 = 与工具名精确匹配。不支持 glob 通配
auth回调鉴权，复用统一鉴权模型 FinxHttpAuth，支持 NONE / API_KEY / BEARER / BASIC / CUSTOM / CUSTOM_HTTP_TOKEN 六种类型
maxRetries仅观察型生效，默认 3；只截断快档重试次数（0~3 档），不影响分钟级阶梯，详见响应与可靠性
signingSecret 更新编辑时不传或传 *** = 保留原密钥；传新值 = 替换；传空字符串 = 清除密钥（后续投递不再签名）
4
DryRun 调试 + 启用
保存后，先用控制台的「DryRun 调试」面板试投递一次再上线。

DryRun 会按你勾选的事件类型逐一构造 mock 事件，用与生产完全一致的信封、签名与鉴权真实调用你的回调地址（同步执行、不重试、不落库、不影响主流程），并返回完整的请求 / 响应快照与分段耗时（durationMs / connectMs / readBodyMs），便于定位慢在建连还是读响应。调试失败时还可使用基于 LLM 的智能诊断分析失败原因，或用自然语言生成配置草稿。看到 200 OK 后即可在列表页打开开关启用 Hook，变更立即生效，无需重启。

  • 拦截型 Hook 的 failureMode=DENY 会阻断主流程，请确认你的服务足够稳定（建议 ≥ 99.9% 可用性）后再启用。
  • 签名密钥仅在创建 / 编辑时由你自行填入，平台不会回显明文；丢失后只能在编辑页重置。
  • 同租户下多个 Hook 命中同一事件时，按 hookOrder 由小到大顺序执行；任一拦截型返回拒绝即提前终止。

响应与可靠性

你的回调服务需要返回什么：

类型响应约定
观察型返回 HTTP 2xx 即视为投递成功，响应体被忽略
拦截型返回 HTTP 2xx + JSON decision 决策（allow / deny / modify，不区分大小写）；空 body 或缺 decision 按放行处理

投递可靠性要点：

  • 拦截型不重试：超时 / 非 2xx / 解析失败直接按 failureMode 降级（ALLOW 放行或 DENY 拒绝）。
  • 观察型阶梯重试：首投失败后先按秒级快档快速重试（档数受 maxRetries 截断），仍失败则进入分钟级阶梯持续重投，默认配置下总投递窗口约 70 分钟；仅 429 / 5xx / 网络类错误触发重试，其余 4xx 不重试。
  • 按 eventId 幂等：重试期间 eventId 与 occurredAt 不变，dispatchedAt / deliveryAttempt 每次更新并重新签名；同一事件可能被多次接收，你的服务必须做幂等去重。
  • 熔断保护：同一回调地址连续出现超时 / 网络类故障会被短暂熔断，期间拦截型直接按 failureMode 短路降级（平台内部保护参数，可能调整）。

信封字段、8 种事件的 context 结构、签名验签与重试阶梯明细，见 Webhook 事件结构。

最佳实践与常见问题

最佳实践：

  • 优先观察型：拦截型处于主流程关键路径，只有确实需要「修改 / 拒绝」输入时才使用。
  • 快速 ACK：拦截型建议 1 秒内返回；耗时业务（二次 RPC、落库）放到观察型里异步处理。
  • 务必验签：生产环境配置 signingSecret 并校验签名 + 时间戳窗口，防伪造与重放。
  • 按 eventId 幂等：观察型重试可能导致同一事件被接收多次，去重后再消费。
  • 拦截型不要租户级：审批 / 拦截型 Hook 首推在应用空间配置并通过 Agent 级挂载精准生效；不推荐在租户级配置拦截型 Hook，失败或拒绝会阻断租户内所有 Agent 的执行。
  • 上线前先 DryRun：用 DryRun 面板验证连通性、签名与响应格式，再打开启用开关。
Q: 为什么我的服务没有收到投递？

按顺序排查：① Hook 是否已启用、事件类型是否勾选正确；② 回调地址是否公网可达（以 http:// 或 https:// 开头）；③ pre_tool_use / post_tool_use 检查 toolNameMatch 是否把目标工具过滤掉了；④ 你的服务是否返回了非 2xx（4xx 不会重试）；⑤ 地址连续超时可能触发熔断，稍后会自动探测恢复。用 DryRun 调试可直接看到完整请求 / 响应快照与分段耗时。

Q: 拦截型 Hook 应该返回什么格式？

HTTP 2xx + JSON：{"decision": "allow"} 放行；{"decision": "deny", "reason": "..."} 拒绝并反馈原因；{"decision": "modify", "modifiedValue": "..."} 修改后放行。decision 不区分大小写；空响应体或缺 decision 按放行处理。完整容错规则见拦截型响应格式。

Q: 如何验证签名、防止重放攻击？

配置 signingSecret 后，平台对「时间戳 + . + 原始请求体」计算 HMAC-SHA256，放在 X-Webhook-Signature 头（sha256=<hex> 格式）。你的服务应先校验 X-Webhook-Timestamp 与本地时钟偏差（建议 ±5 分钟窗口），再用同一密钥重算签名并做常时间比较。详见签名算法。

Q: 如何让 Hook 只对某个 Agent 生效？

不要用租户级配置，改用 Agent 级挂载。在应用空间「Webhook」页创建配置，再进入「智能体 → Agent 详情 → 『Webhook（已挂载 N）』卡片 → 管理」勾选并保存。注意保存是全量覆盖语义，以本次勾选结果为准，取消全部勾选即清空该 Agent 的挂载。

Q: 多个 Hook 命中同一事件时按什么顺序执行？

租户级 Hook 与 Agent 挂载的 Webhook 合并后，按 hookOrder（取值 0~9999，默认 100）升序统一执行；拦截型事件中任一 Hook 返回拒绝即短路，后续 Hook 不再执行。