Webhook
什么是 Webhook
Webhook 是用户通过自定义回调的方式来改变 Web 应用的一种行为，这些回调可以由不是该 Web 应用官方的第三方用户或者开发人员来维护，修改。通过 Webhook，你可以自定义一些行为通知到指定的 URL 去。
用户如何在 Tracup 上设置第三方 Webhook 服务？
第一步：用户登录 Tracup
第二步：点击某个项目，然后点击头部菜单中的「设置」
第三步：在「设置」页面中，找到「Webhook」，然后点击「创建 Webhook」
第四步：在创建 Webhook 页面中，填写以下内容：
- 名称（随便起一个名字，一般可以用第三方服务名称，例如 Slack）
- URL（填写第三方服务提供的 Webhook 接收 URL）
- 校验密钥（用于校验来源是否正确。如果第三方 Webhook 服务要求时则填写，否则可以不填）
- 选择需要通知的类目，如问题，项目，邀请成员等。
如下图所示：
第五步：点击确定按钮即可生效。
webhook 参考
Header
每条消息 Webhook 请求均为 POST 请求，请求主体是以 UTF-8 字符集编码的 JSON 文本，请求头包含 Webhook 发送服务器数据及校验信息。
关键的 Header 内容及含义参见下表
| 字段 | 含义 |
|---|---|
| Content-Type | 请求数据类型，均为 application/json |
| Content-Length | 请求体的长度 |
| User-Agent | Webhook 发送机器的 ID |
| X-Tracup-ID | Webhook 事件的唯一识别 ID |
| X-Tracup-SIG | Webhook 请求体验证字段，当设置 校验密钥 时，此值为 以 校验密钥 为 key 以 请求体 为 消息 的 SHA1 消息摘要值 |
请求体
请求体是以 UTF-8 字符集编码的 JSON 文本。 包含以下字段。
| 字段 | 类型／模型 | 含义 |
|---|---|---|
| type | String | 事件的类型 |
| action | String | 事件的动作 create update delete 的一种 |
| field | String | 对于 update 事件，用于描述 data 字段内变更的字段 |
| affected | String | 发生变更数据的 ID |
| project | Project* | 项目信息 |
| sender | Member* | 产生事件的用户信息，一般为操作者 |
| time | Int | 事件产生时的 Unix 时间戳 |
对于不同的事件 type , data 字段内的数据模型也会有所不同。
| 事件 type | data 字段的模型 | 含义 |
|---|---|---|
| member | Member* | 成员列表发生变动 |
| module | Module* | 模块列表发生变动 |
| version | Version* | 版本列表发生变动 |
| type | Type* | 问题类型列表发生变动 |
| project | Project* | 项目信息发生变动 |
| file | File* | 项目内文件发生变动 |
| issue | Issue* | 问题发生变动 |
*数据模型，下文会有详细描述
数据模型
Member
Member 模型用于描述项目内人员的信息
| Key | 类型 | 含义 |
|---|---|---|
| key | String | ID |
| name | String | 名字 |
| role | Int | 角色 0.未知 1.管理员 2.开发人员 3.测试人员 4.项目创建者 5.被邀请但尚未加入项目的成员 |
Module
Module 模型用于描述项目内模块的设置
| Key | 类型 | 含义 |
|---|---|---|
| key | String | ID |
| name | String | 名称 |
Version
Version 模型用于描述项目内版本的设置
| Key | 类型 | 含义 |
|---|---|---|
| key | String | ID |
| name | String | 名称 |
| status | String | 发布状态 0.未发布 1.已发布 |
| start | Int | 开始时间 Unix 时间戳 |
| end | Int | 结束时间 Unix 时间戳 |
Type
Type 模型用于描述项目内问题类型的设置
| Key | 类型 | 含义 |
|---|---|---|
| key | String | ID |
| name | String | 名称 |
File
File 模型用于描述文件信息
| Key | 类型／模型 | 含义 |
|---|---|---|
| key | String | ID |
| name | String | 文件名 |
| mime | String | 文件 MIME 类型 |
| size | Int | 文件大小 (以字节为单位) |
| url | String | 下载路径 |
| creator | Member* | 创建者信息 |
| created | Int | 创建时间 Unix 时间戳 |
Note
Note 模型用于描述问题内的备注信息
| Key | 类型／模型 | 含义 |
|---|---|---|
| key | String | ID |
| content | String | 内容 |
| creator | Member* | 创建者信息 |
| updated | Int | 更新时间 Unix 时间戳 |
Project
Project 模型用于描述项目设置
| Key | 类型／模型 | 含义 |
|---|---|---|
| key | String | ID |
| name | String | 名称 |
| description | String | 描述 |
| creator | Member* | 创建者信息 |
| recycled | Boolean | 描述项目是否被回收 |
| created | Int | 创建时间 Unix 时间戳 |
Wiki
Project 模型用于描述项内 Wiki 的内容
| Key | 类型／模型 | 含义 |
|---|---|---|
| key | String | ID |
| uri | String | Wiki URI |
| content | String | 内容 |
| version | Int | Wiki 的修订版本 |
| creator | Member* | 描述项目是否被回收 |
| attachments | File[]* | 附件 File 数组 |
| created | Int | 创建时间 Unix 时间戳 |
| update | Int | 创建时间 Unix 时间戳 |
Issue
Issue 模型用于描述项目内 问题 的内容
| Key | 类型／模型 | 含义 |
|---|---|---|
| key | String | ID |
| parentIssue | Issue* | 父问题 （如果没有则为空） |
| number | Int | 问题编号 |
| type | Type* | 问题类型 |
| title | String | 主题 |
| description | String | 描述 （Markdown） |
| priority | Int | 优先级 1.高 2.中 3.低 |
| status | Int | 状态 1.新建 2.处理中 3.已解决 4.已忽略 5.待反馈 6.已关闭 7.重新打开 |
| creator | Member* | 创建者信息 |
| assignee | Member* | 被指派者信息 |
| version | Version* | 版本 |
| module | Module* | 模块 |
| attachments | File[]* | 附件 File 数组 |
| followers | Member[]* | 关注者 Member 数组 |
| notes | Note[]* | 备注 Note 数组 |
| finished | Int | 结束时间 Unix 时间戳 |
| created | Int | 创建时间 Unix 时间戳 |
| updated | Int | 更新时间 Unix 时间戳 |
*数据模型，本节内有描述
中文
English