配置端点
管理员在工作区设置的 Webhooks 页面添加公网 HTTPS 接收地址,选择需要的事件。实例须先配置服务端加密密钥;未启用时不能创建端点。仅接收有权读取的团队数据,工作区管理员不会自动收到私有团队事件。
当前支持 issue、comment、project、cycle 的 created、updated、deleted 事件。每个事件都含 id、type、workspaceId、entityId 和 occurredAt。评论事件还携带所属资源的 ID,便于通过 API 回查。
通过事件读取评论
comment.created、comment.updated 和 comment.deleted 的 entityId 是内部评论 ID。验签后,将事件里的 workspaceId 用作 X-Workspace-Id 请求头,并使用具备读取权限的 API Key。
| 评论来源 | 事件携带的所属资源 ID | 读取评论 |
|---|---|---|
| Issue | issueId |
GET /api/issues/{issueId}/comments,找到 id 等于 entityId 的条目。也可使用 MCP get_issue 并传入 issueId。 |
| 项目描述 | projectId |
GET /api/projects/{projectId}/comments/{entityId} |
| 项目更新 | projectId 和 projectUpdateId |
GET /api/projects/{projectId}/updates/{projectUpdateId}/comments/{entityId} |
事件没有评论正文。收到删除事件时,可用这些 ID 清理缓存。若评论在回查前已被删除,列表可能找不到该条目,单条读取可能返回 404。历史事件保留原始载荷,重试或重放时可能缺少所属资源 ID。
保存签名密钥
创建或修改端点时签名密钥只返回一次,立即存入接收端的秘密存储。普通列表不会再次显示明文。修改端点会更换密钥和配置版本,并取消旧版本排队投递;旧事件不能转发到新的 URL。
编辑冲突时重新加载配置,不自动覆盖其他管理员的修改。删除或撤权无法追回已经发出的请求。
验证原始请求
读取以下请求头,并在解析或重排 JSON 前使用原始 body 验签:
X-Task-Manager-Event-Id
X-Task-Manager-Timestamp
X-Task-Manager-Signature: sha256=<hex>
HMAC-SHA256(signingSecret, eventID + "." + timestamp + "." + rawBody)
使用恒定时间比较,限制时间戳偏差,并按事件 ID 幂等去重。先校验来源,再执行业务写入;不要把请求中的任意 URL 当作可信下载目标。
重试与日志
2xx 表示接收成功。网络失败或其他状态最多自动尝试八次,间隔从一分钟指数增长至一小时。接收端可能已处理但确认丢失,因此可能收到重复事件。
管理员可查看投递记录并在允许的终态重放当前配置版本的事件,事件 ID 保持不变。接收端应继续去重;查看或重放仍须具备当前权限。系统拒绝内网、回环、元数据地址与重定向,不要依赖 Webhooks 访问内部管理服务。