WebHook
事件总览
查看全部 WebHook 事件、触发含义、主要载荷和过滤规则。
Poco 当前支持 10 种事件。事件名是稳定的路由依据；接收端应忽略暂时不认识的额外字段，以便同一 schema_version 下增加信息时保持可用。
事件列表
| 事件 | 何时触发 | 主要对象 | 详细说明 |
|---|---|---|---|
session.completed | Agent 运行成功完成 | session、run、summary | 会话事件 |
session.failed | Agent 运行失败 | session、run、错误信息 | 会话事件 |
session.stopped | 会话被用户停止 | session、run、停止原因 | 会话事件 |
scheduled_task.run_status_changed | 定时任务运行状态变化 | scheduled_task、run、session | 自动化与交互事件 |
user_input.requested | Agent 请求人工输入 | user_input、session | 自动化与交互事件 |
user_input.answered | 用户完成回答 | user_input、session | 自动化与交互事件 |
workbench.insight_status_changed | 工作台洞察状态变化 | insight | 自动化与交互事件 |
publish_page.published | 新发布页版本成功生成 | publish_page、version、session | 发布页事件 |
publish_page.failed | 自动发布失败 | publish_page、job、error、session | 发布页事件 |
workspace_export.completed | 工作区导出完成 | workspace_export、session、run | 工作区导出事件 |
过滤顺序
一个事件只有依次通过以下条件才会投递：
- WebHook 已启用。
event_types包含本次事件。- 对会话过滤事件，
session_kinds包含本次会话类型。 scope=project时，事件能关联到项目，且项目 ID 与配置一致。
真实投递按上述全部条件匹配；测试跳过 enabled 检查，因此不会因禁用返回 disabled。其他 filtered_reason 表示匹配失败原因：
| 值 | 含义 |
|---|---|
event_type_filtered | 未订阅该事件 |
session_kind_filtered | 会话类型未被选中 |
scope_project_missing | 项目级配置本身缺少项目 ID |
session_project_missing | 事件或测试会话没有关联项目 |
project_mismatch | 事件项目与配置项目不同 |
会话类型过滤适用范围
只有 session.completed、session.failed、session.stopped 和 workspace_export.completed 使用 session_kinds。其他事件即使带有 session 字段，也不会因此过滤。
事件 ID 与幂等
event_id 在同一业务事件的重试中保持不变，当前 meta.idempotency_key 与其一致。接收端可以选一个作为幂等键，推荐直接使用请求头 X-Poco-Event-Id，并在数据库或 Redis 中设置合理保留期。
is_test=true 表示测试推送。生产业务处理可以记录它，但通常不应触发真实下游动作。