Webhooks

由管理员订阅实体变化,验证签名并按事件 ID 安全去重。

文档对应应用版本 8c09715b · 文档修订 d2d4fba5

    配置端点

    管理员在工作区设置的 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 访问内部管理服务。