Support

Webhook

什么是 Webhook

Webhook 是用户通过自定义回调的方式来改变 Web 应用的一种行为,这些回调可以由不是该 Web 应用官方的第三方用户或者开发人员来维护,修改。通过 Webhook,你可以自定义一些行为通知到指定的 URL 去。

用户如何在 Tracup 上设置第三方 Webhook 服务?

第一步:用户登录 Tracup

第二步:点击某个项目,然后点击头部菜单中的「设置」

第三步:在「设置」页面中,找到「Webhook」,然后点击「创建 Webhook」

第四步:在创建 Webhook 页面中,填写以下内容:

  1. 名称(随便起一个名字,一般可以用第三方服务名称,例如 Slack)
  2. URL(填写第三方服务提供的 Webhook 接收 URL)
  3. 校验密钥(用于校验来源是否正确。如果第三方 Webhook 服务要求时则填写,否则可以不填)
  4. 选择需要通知的类目,如问题,项目,邀请成员等。

如下图所示:

第五步:点击确定按钮即可生效。

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

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