配置 WebHook

说明 WebHook 的地址、事件、用户级与系统级范围、会话过滤、超时和重试参数。

可在 Poco 设置页的 WebHook 页面创建配置，也可以使用 /api/v1/webhooks 接口管理。配置决定“哪些事件发给哪个地址”，不会改变事件本身的业务数据。

配置项

字段	类型	默认值	说明
`name`	string	无	配置名称；同一归属范围内不能重名
`url`	string	无	完整 HTTP(S) 接收地址
`owner_scope`	`user` / `system`	`user`	用户级或系统级；系统级仅管理员可管理
`scope`	`global` / `project`	`global`	接收所有匹配事件，或只接收指定项目事件
`project_id`	UUID / null	`null`	`scope=project` 时必填
`enabled`	boolean	`true`	是否启用投递
`event_types`	string[]	`["session.completed"]`	订阅的事件类型
`session_kinds`	string[]	`chat`、`api`、`scheduled` 全部	会话类型过滤
`secret`	string / null	`null`	HMAC-SHA256 签名密钥
`timeout_ms`	integer	`5000`	单次请求超时，范围 `500-60000` 毫秒
`retry_count`	integer	`2`	首次请求失败后的重试次数，范围 `0-6`
`retry_backoff_ms`	integer	`800`	第一次重试前的退避，范围 `100-30000` 毫秒

retry_count=2 表示最多请求 3 次：首次 1 次，加重试 2 次。

用户级与系统级

类型	事件范围	项目范围	管理权限
用户级 `user`	当前配置所属用户的事件	支持 `global` 或 `project`	当前用户管理自己的配置
系统级 `system`	所有用户中满足过滤条件的事件	只支持 `global`	仅管理员可管理

系统级事件中的 user 表示事件实际所属用户；webhook.owner_scope 表示投递来自用户级还是系统级配置。系统级 WebHook 不能改成项目范围。

事件与会话类型过滤

session_kinds 只作用于以下事件：

session.completed
session.failed
session.stopped
workspace_export.completed

可选值：

值	来源
`chat`	Poco 页面中的普通对话
`api`	OpenAI Chat Completions 或 Messages 创建的 API 会话
`scheduled`	定时任务会话

定时任务状态、人工输入、工作台洞察和发布页事件不会使用 session_kinds 过滤。项目范围仍会根据事件关联项目进行匹配。

推送地址

地址必须包含 http 或 https scheme 和有效主机，例如：

https://integration.example.com/webhooks/poco

生产环境不建议使用 HTTP。确认防火墙、DNS、TLS 证书和反向代理允许 Poco 服务器访问该地址。

创建配置接口

端点：POST /api/v1/webhooks

该接口使用 Poco 登录 Token 鉴权：

curl -X POST 'https://<poco-host>/api/v1/webhooks' \
  -H 'Authorization: Bearer <poco-login-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "生产任务通知",
    "url": "https://integration.example.com/webhooks/poco",
    "owner_scope": "user",
    "scope": "global",
    "enabled": true,
    "event_types": [
      "session.completed",
      "session.failed",
      "workspace_export.completed"
    ],
    "session_kinds": ["api", "scheduled"],
    "secret": "replace-with-a-strong-secret",
    "timeout_ms": 5000,
    "retry_count": 2,
    "retry_backoff_ms": 800
  }'

响应只返回 has_secret，不会返回明文密钥。更新时如不传 secret，保留现有密钥；传 clear_secret=true 可清除密钥。

管理接口

方法与端点	说明
`GET /api/v1/webhooks?owner_scope=user`	列出当前用户的 WebHook
`GET /api/v1/webhooks?owner_scope=system`	列出系统 WebHook，仅管理员
`PATCH /api/v1/webhooks/{webhook_id}`	更新配置；`owner_scope` 不能修改
`DELETE /api/v1/webhooks/{webhook_id}`	删除配置
`POST /api/v1/webhooks/{webhook_id}/test`	发送测试事件

配置项

用户级与系统级

事件与会话类型过滤

推送地址

创建配置接口

管理接口

推荐配置

On this page