WebHook
发布页事件
处理发布页新版本成功生成或自动发布失败，并通过公开 API 读取版本内容。
发布页事件与会话事件分开触发。会话成功不代表发布成功；如果外部系统关心最终可访问页面，应订阅 publish_page.published 和 publish_page.failed。
发布成功
事件：publish_page.published
{
"schema_version": "v1",
"event_type": "publish_page.published",
"event_id": "7ec2d1a1-0000-4000-8000-000000000001",
"occurred_at": "2026-02-15T14:35:00+00:00",
"is_test": false,
"user": {
"user_id": "1234567890",
"username": "alice",
"full_name": "Alice",
"department": "研发",
"role": "user"
},
"webhook": {
"id": 13,
"owner_scope": "user"
},
"publish_page": {
"publish_center_id": "8c010000-0000-4000-8000-000000000001",
"name": "日报发布",
"publish_key": "daily-report",
"source_type": "scheduled_task",
"category": "日报",
"public_to_board_enabled": true
},
"version": {
"version_no": 3,
"session_id": "5f6a0000-0000-4000-8000-000000000001",
"entry_path": "/report.html",
"share_code": "AbC123xYz0",
"published_url": "/share/p/daily-report",
"trigger_type": "auto",
"reason": "AI selected the first publishable report"
},
"session": {
"session_id": "5f6a0000-0000-4000-8000-000000000001",
"title": "日报总结",
"kind": "scheduled",
"project_id": "97d20000-0000-4000-8000-000000000001"
},
"meta": {
"trigger": "publish_page.published",
"source": "poco.backend.publish_center",
"idempotency_key": "7ec2d1a1-0000-4000-8000-000000000001"
}
}核心字段
| 字段 | 说明 |
|---|---|
publish_page.publish_center_id | 发布中心内部 ID |
publish_page.publish_key | 公开访问 key，对应 /share/p/{publish_key} |
publish_page.source_type | scheduled_task 或 existing_session |
publish_page.public_to_board_enabled | 是否公开到发布广场 |
version.version_no | 本次新增的版本号 |
version.entry_path | 该版本入口文件路径 |
version.share_code | 该版本分享码 |
version.published_url | 发布页访问路径；如需绝对地址应与 Poco 基础地址拼接 |
version.trigger_type | manual 或 auto |
version.reason | 发布原因，可能为 null |
session.project_id | 关联项目，可能为 null |
读取发布内容
事件只携带发布标识，不内嵌完整文件内容。可使用以下公开接口：
| 端点 | 用途 |
|---|---|
GET /api/v1/public/publishes/{publish_key} | 当前发布页和最新版本入口文件 |
GET /api/v1/public/publishes/{publish_key}/versions | 版本列表 |
GET /api/v1/public/publishes/{publish_key}/versions/{version_no}/files | 指定版本文件树 |
GET /api/v1/public/shares/{share_code} | 按分享码读取对应版本 |
字段详情见 公开发布页 API。
发布失败
事件：publish_page.failed
自动发布失败时触发，主要字段：
| 字段 | 说明 |
|---|---|
publish_page.publish_center_id | 发布中心 ID |
publish_page.name | 发布页名称 |
publish_page.publish_key | 发布页公开 key |
job.job_id | 自动发布任务 ID，可能为 null |
job.run_id | 关联运行 ID，可能为 null |
job.scheduled_task_id | 关联定时任务 ID，可能为 null |
job.status | 发布任务状态 |
job.attempt_count | 已尝试次数 |
job.max_attempts | 最大尝试次数 |
job.last_error | 发布任务最后一次错误 |
error.message | 本次失败错误信息 |
session | 关联会话摘要 |
接收端可以用 job.job_id 关联发布任务，用 event_id 处理 WebHook 重试。不要因为 WebHook 自身重试而再次无条件创建发布任务。