测试与排查

使用测试推送验证连通性、签名和过滤条件，并通过真实业务事件完成上线验收。

WebHook 测试分两层：测试推送用于验证目标地址、签名和过滤配置；真实任务用于验证实际事件是否在正确业务时机触发。两层都通过才能认为接入完成。

发送测试事件

端点：POST /api/v1/webhooks/{webhook_id}/test

使用 Poco 登录 Token 鉴权。建议提供真实 session_id，用于检查会话类型与项目匹配。测试会跳过 enabled 检查，禁用配置也能测试；真实投递只使用启用配置。洞察真实项目匹配来自关联项目集合，单个测试会话不能完全替代真实场景。

curl -X POST 'https://<poco-host>/api/v1/webhooks/<webhook-id>/test' \
  -H 'Authorization: Bearer <poco-login-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "event_type": "session.completed",
    "session_id": "<session-uuid>"
  }'

测试发布页和工作区导出事件时，只需替换 event_type：

{ "event_type": "publish_page.published", "session_id": "<session-uuid>" }

{ "event_type": "workspace_export.completed", "session_id": "<session-uuid>" }

测试载荷中的 is_test 为 true。接收端可以正常验签和入库，但不要触发生产下游动作。

测试响应

响应 data 包含：

字段	说明
`delivered`	目标 URL 是否最终返回 2xx
`matched`	是否通过 WebHook 过滤规则
`filtered_reason`	未匹配原因；匹配成功时为 `null`
`tested_session_id`	本次用于匹配的会话 ID
`tested_session_kind`	`chat`、`api` 或 `scheduled`
`tested_project_id`	会话所属项目，可能为 `null`
`status_code`	接收端最终 HTTP 状态码，网络错误时可能为空
`error_message`	投递失败原因，成功时为空
`event_id`	本次测试事件 ID

matched=true 只表示过滤通过，delivered=true 才表示目标地址返回了 2xx。

过滤失败

`filtered_reason`	原因	修复方式
`event_type_filtered`	没有订阅测试事件	将事件加入 `event_types`
`session_kind_filtered`	会话类型不在过滤范围	增加对应 `session_kinds`
`scope_project_missing`	项目级配置缺少项目	重新保存有效 `project_id`
`session_project_missing`	测试会话没有项目	使用属于目标项目的会话，或改为全局范围
`project_mismatch`	会话项目与配置项目不同	使用匹配会话或修改配置项目

不传 session_id 时，测试使用 kind=chat、project_id=null 的默认上下文，只能验证基本连通性，不能证明真实任务一定能通过过滤。

投递失败

按以下顺序排查：

status_code 是否为 2xx。
Poco 服务器是否能解析接收域名并建立 HTTPS 连接。
TLS 证书链是否完整且未过期。
防火墙、网关或 WAF 是否允许 Poco 来源。
接收端是否在超时时间内返回。
验签时是否使用原始请求体和正确密钥。
接收端日志中的 event_id 是否与测试响应一致。

HTTP 401 通常是签名或鉴权校验失败；404 常见于路径配置错误；429 表示接收端限流；5xx 表示接收端异常并会触发重试。

真实事件验收

测试推送通过后，至少验证以下细节：

创建一个符合 scope 和 session_kinds 的真实会话，确认收到正确结束事件。
制造一个可控失败或停止场景，确认失败与停止不会被当作完成处理。
如果业务读取文件，确认在 workspace_export.completed 后能通过 API 获取文件。
如果业务读取发布页，确认 publish_page.published 中的版本号与公开 API 一致。
重放已保存的同一次测试 HTTP 请求，或模拟接收端首次返回 5xx，确认业务只处理一次。
使用错误签名和过期时间戳请求接收端，确认返回 4xx。
确认未知但合法事件不会让接收端崩溃。

每次调用测试接口都会生成新的 event_id，不是重放旧事件。验证去重应复用同一次投递的 event_id，而不是连续点击两次测试。

上线检查清单

接收地址使用 HTTPS。
签名密钥已配置且未写入代码仓库。
原始请求体验签、时间窗口和恒定时间比较均已实现。
event_id 幂等存储支持重启和多实例。
请求完成可靠入队后快速返回 2xx。
日志能按 event_id 追踪，但不包含敏感凭证。
测试推送与至少一个真实业务事件都已验证。