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 时间戳`

*数据模型，本节内有描述