WebHook
介绍
让 Poco 在会话、定时任务、人工输入、发布页或工作区导出状态变化时主动通知外部系统。
WebHook 是 Poco 向外部系统发送的 HTTP POST 通知。你的系统提供一个公开可访问的接收地址，Poco 在订阅事件发生时把 JSON 数据推送过去。
典型流程
- 在接收系统创建 HTTPS 端点。
- 在 Poco 配置推送地址、事件、范围、签名密钥和重试策略。
- 接收端使用原始请求体完成验签。
- 使用
event_id做幂等判断。 - 快速返回 HTTP 2xx，再异步执行耗时业务。
- 先测试推送，再用真实会话验证事件过滤和业务处理。
支持的事件
| 业务 | 事件 |
|---|---|
| 会话 | session.completed、session.failed、session.stopped |
| 定时任务 | scheduled_task.run_status_changed |
| 人工输入 | user_input.requested、user_input.answered |
| 工作台洞察 | workbench.insight_status_changed |
| 发布页 | publish_page.published、publish_page.failed |
| 工作区导出 | workspace_export.completed |
WebHook 不等于 API 响应
API 对话响应适合当前请求立即消费；WebHook 适合异步状态通知。一个业务流程可能同时使用两者，例如：
- Messages 接口创建任务，WebHook 在会话完成后通知工单系统。
session.completed表示 Agent 运行完成，workspace_export.completed才表示工作区文件已导出。publish_page.published表示发布页版本已生成，比会话完成更适合触发内容同步。
接入要求
- 生产地址使用 HTTPS，并保证 Poco 服务器可以访问。
- 始终配置签名密钥，并验证时间戳，防止伪造和重放。
- 接收端必须幂等；Poco 的失败重试可能投递同一个
event_id多次。 - 只有 HTTP 2xx 被视为成功，响应正文格式不影响成功判断。
建议按顺序阅读配置 WebHook、投递协议、签名校验和接收端实现。