WebHook
工作区导出事件
在工作区文件清单和归档准备完成后接收通知，并通过 API 获取可访问文件。
事件：workspace_export.completed
该事件表示工作区导出流程完成，适合驱动文件同步、归档下载或后续审批。它与 session.completed 分开触发，因为 Agent 运行结束后，文件清单和归档还可能需要时间准备。
请求体示例
{
"schema_version": "v1",
"event_type": "workspace_export.completed",
"event_id": "f1b5a6d4-0000-4000-8000-000000000001",
"occurred_at": "2026-02-15T14:32:00+00:00",
"is_test": false,
"user": {
"user_id": "1234567890",
"username": "alice",
"full_name": "Alice",
"department": "研发",
"role": "user"
},
"webhook": {
"id": 14,
"owner_scope": "user"
},
"workspace_export": {
"status": "ready",
"files_prefix": "workspaces/user-1/session/files",
"manifest_key": "workspaces/user-1/session/manifest.json",
"archive_key": "workspaces/user-1/session/archive.zip",
"archive_available": true
},
"session": {
"session_id": "5f6a0000-0000-4000-8000-000000000001",
"title": "日报总结",
"kind": "chat",
"status": "completed",
"project_id": "97d20000-0000-4000-8000-000000000001",
"created_at": "2026-02-15T14:20:00+00:00",
"updated_at": "2026-02-15T14:32:00+00:00"
},
"run": {
"run_id": "6dc90000-0000-4000-8000-000000000001",
"turn_id": "20cf0000-0000-4000-8000-000000000001",
"status": "completed",
"schedule_mode": "immediate",
"scheduled_task_id": null,
"started_at": "2026-02-15T14:20:10+00:00",
"finished_at": "2026-02-15T14:29:58+00:00"
},
"meta": {
"trigger": "workspace_export.completed",
"source": "poco.backend.callback.workspace_export",
"idempotency_key": "f1b5a6d4-0000-4000-8000-000000000001",
"capability_profile_version": 3
}
}核心字段
| 字段 | 说明 |
|---|---|
workspace_export.status | 当前完成事件固定为 ready |
workspace_export.files_prefix | 文件对象前缀，可能为 null |
workspace_export.manifest_key | 文件清单对象 key，可能为 null |
workspace_export.archive_key | 工作区归档对象 key，可能为 null |
workspace_export.archive_available | 是否存在归档包 |
session.session_id | 关联会话 ID |
session.kind | chat、api 或 scheduled |
session.project_id | 关联项目，可能为 null |
run.run_id、run.turn_id | 关联运行和轮次；无法解析时可能为 null |
run.scheduled_task_id | 定时任务 ID，可能为 null |
对象 key 是后端资源引用，不是公开下载 URL。接收端不要自行拼接对象存储地址，也不要假设存储桶可以公开访问。
获取实际文件
API 会话可调用：
GET /openapi/v1/sessions/{session_id}/artifacts它返回文件树和具有访问时效的下载地址，详见产物管理。管理员看板接入也可使用 Office Mode 的工作区文件与归档接口。
过滤规则
该事件使用 session_kinds 过滤。只关心 API 任务文件时，将会话类型设置为 api；定时任务文件设置为 scheduled。项目级 WebHook 还会要求会话项目与配置项目一致。
推荐处理流程
- 校验签名并按
event_id去重。 - 检查
workspace_export.status和archive_available。 - 使用
session_id调用 API 获取当前有效下载地址。 - 把文件同步到自己的存储后返回业务完成状态。
WebHook 接收请求本身仍应快速返回；文件下载放到内部队列执行。