Support

Tracup 第三方服务集成

什么是 Webhook?

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

什么是 Tracup?

Tracup蒲公英 旗下的一款提供给软件开发团队进行 bug 跟踪的 SaaS 云服务。

目前,Tracup 已经支持了 Webhook 协议的数据输出。本文档主要介绍第三方服务如何进行对接。

请求方法

当 Tracup 上有事件发生时,Tracup 会将事件相关的数据,以 HTTP POST 的形式发送到用户设置的第三方 Webhook 地址上。第三方 Webhook 服务可以使用获取 POST RAW 数据的方式来获取消息数据。例如,在 PHP 中可以用如下方式获取数据:

$data = file_get_contents('php://input');

或者:

$data = $HTTP_RAW_POST_DATA;

获取到数据之后,再进行 JSON DECODE 即可解析出具体的数据,例如:

$info = json_decode($data, true);

之后,第三方 Webhook 服务即可将获取到的消息数据,根据自身的业务逻辑进行相应处理,例如可以显示在自己平台的消息流、或通知中心等。

数据体中 type 和 action 的取值

当 Tracup 上事件发生时,都会向第三方 Webhook 服务推送事件相关数据。向第三方推送的数据包中,都包含 typeaction 字段。type 表示了事件的类型,而 action 表示了事件的动作。关于 typeaction 的取值,可见如下表格。

事件类型 type action
项目 project create,update,delete
问题 issue create,update,delete
成员 member create,update,delete
文件 file create,update,delete
Wiki wiki create,update,delete
版本 version create,update,delete
模块 module create,update,delete
问题类型 type create,update,delete

数据示例

项目
{
  "type": "project",
  "action": "update",
  "field": "description",
  "affected": "83b17e3d158ae72518a19f7de9ce61e7",
  "data": {
    "key": "83b17e3d158ae72518a19f7de9ce61e7",
    "name": "小测测",
    "description": "测试测试hahah",
    "creator": {
      "role": 4,
      "key": "4a5bc52e6763795e18b69bd82dd23a9e",
      "name": "rexshi"
    },
    "recycled": 0,
    "created": 1462767369
  },
  "project": {
    "key": "83b17e3d158ae72518a19f7de9ce61e7",
    "name": "小测测",
    "description": "测试测试hahah",
    "creator": {
      "role": 4,
      "key": "4a5bc52e6763795e18b69bd82dd23a9e",
      "name": "rexshi"
    },
    "recycled": 0,
    "created": 1462767369
  },
  "sender": {
    "role": 4,
    "key": "4a5bc52e6763795e18b69bd82dd23a9e",
    "name": "rexshi"
  },
  "time": 1494245243
}
问题
{
  "type": "issue",
  "action": "create",
  "field": "",
  "affected": "bec81b7a64ba9433e4ecd4d53ceca6fb",
  "data": {
    "key": "bec81b7a64ba9433e4ecd4d53ceca6fb",
    "parentIssue": [],
    "number": 83,
    "description": "",
    "assignee": null,
    "priority": 2,
    "status": 1,
    "creator": {
      "role": 4,
      "key": "4a5bc52e6763795e18b69bd82dd23a9e",
      "name": "rexshi"
    },
    "version": [],
    "module": [],
    "type": {
      "key": "2d05d57e5fa9bc13f382490d7fee366e",
      "name": "undefined"
    },
    "finished": 1495814399,
    "created": 1493991297,
    "updated": 1493991297,
    "attachments": [],
    "followers": [],
    "notes": []
  },
  "project": {
    "key": "83b17e3d158ae72518a19f7de9ce61e7",
    "name": "小测测",
    "description": "测试测试 http://www.pgyer.com",
    "creator": {
      "role": 4,
      "key": "4a5bc52e6763795e18b69bd82dd23a9e",
      "name": "rexshi"
    },
    "recycled": 0,
    "created": 1462767369
  },
  "sender": {
    "role": 4,
    "key": "4a5bc52e6763795e18b69bd82dd23a9e",
    "name": "rexshi"
  },
  "time": 1493991297
}
成员
{
  "type": "member",
  "action": "create",
  "field": "",
  "affected": "807b7a4cfa4bea0fc3342607cf790420",
  "data": {
    "role": 3,
    "key": "8549b5cc2395871a01d1715bd4c99f04",
    "name": "lilyliu"
  },
  "project": {
    "key": "83b17e3d158ae72518a19f7de9ce61e7",
    "name": "小测测",
    "description": "测试测试 http://www.pgyer.com",
    "creator": {
      "role": 4,
      "key": "4a5bc52e6763795e18b69bd82dd23a9e",
      "name": "rexshi"
    },
    "recycled": 0,
    "created": 1462767369
  },
  "sender": {
    "role": 4,
    "key": "4a5bc52e6763795e18b69bd82dd23a9e",
    "name": "rexshi"
  },
  "time": 1493895191
}
文件
{
  "type": "file",
  "action": "create",
  "field": "",
  "affected": "55b19a41e389c752e5756c1e5d4ca891",
  "data": {
    "key": "55b19a41e389c752e5756c1e5d4ca891",
    "name": "73915AD6-5025-4B82-B8CE-43AF06220898.png",
    "url": "http://7xrtzv.com1.z0.glb.clouddn.com/o_1bfjvclf31k0m1qeb1nvsgfc6fc29.png",
    "size": 17964,
    "mime": "image/png",
    "creator": {
      "role": 4,
      "key": "4a5bc52e6763795e18b69bd82dd23a9e",
      "name": "rexshi"
    },
    "created": 1494245335
  },
  "project": {
    "key": "83b17e3d158ae72518a19f7de9ce61e7",
    "name": "小测测",
    "description": "测试测试hahah",
    "creator": {
      "role": 4,
      "key": "4a5bc52e6763795e18b69bd82dd23a9e",
      "name": "rexshi"
    },
    "recycled": 0,
    "created": 1462767369
  },
  "sender": {
    "role": 4,
    "key": "4a5bc52e6763795e18b69bd82dd23a9e",
    "name": "rexshi"
  },
  "time": 1494245335
}
Wiki
{
  "type": "wiki",
  "action": "update",
  "field": "*",
  "affected": "913a584261ce69f4e12a2a03b6edef3b",
  "data": {
    "creator": {
      "role": 4,
      "key": "4a5bc52e6763795e18b69bd82dd23a9e",
      "name": "rexshi"
    },
    "created": false,
    "attachments": []
  },
  "project": {
    "key": "83b17e3d158ae72518a19f7de9ce61e7",
    "name": "小测测",
    "description": "测试测试 http://www.pgyer.com",
    "creator": {
      "role": 4,
      "key": "4a5bc52e6763795e18b69bd82dd23a9e",
      "name": "rexshi"
    },
    "recycled": 0,
    "created": 1462767369
  },
  "sender": {
    "role": 4,
    "key": "4a5bc52e6763795e18b69bd82dd23a9e",
    "name": "rexshi"
  },
  "time": 1493895311
}
版本
{
  "type": "version",
  "action": "create",
  "field": "",
  "affected": "84afcd717ab9ae5f2c10d8300502ab46",
  "data": {
    "key": "84afcd717ab9ae5f2c10d8300502ab46",
    "name": "22",
    "start": -62170013143,
    "end": -62169926744,
    "status": 0,
    "creator": null
  },
  "project": {
    "key": "83b17e3d158ae72518a19f7de9ce61e7",
    "name": "小测测",
    "description": "测试测试 http://www.pgyer.com",
    "creator": {
      "role": 4,
      "key": "4a5bc52e6763795e18b69bd82dd23a9e",
      "name": "rexshi"
    },
    "recycled": 0,
    "created": 1462767369
  },
  "sender": {
    "role": 4,
    "key": "4a5bc52e6763795e18b69bd82dd23a9e",
    "name": "rexshi"
  },
  "time": 1493895219
}
模块
{
  "type": "module",
  "action": "create",
  "field": "",
  "affected": "53fb937cd15a56e15688f060b5e4a499",
  "data": {
    "key": "53fb937cd15a56e15688f060b5e4a499",
    "name": "fdsfdsfds"
  },
  "project": {
    "key": "83b17e3d158ae72518a19f7de9ce61e7",
    "name": "小测测",
    "description": "测试测试 http://www.pgyer.com",
    "creator": {
      "role": 4,
      "key": "4a5bc52e6763795e18b69bd82dd23a9e",
      "name": "rexshi"
    },
    "recycled": 0,
    "created": 1462767369
  },
  "sender": {
    "role": 4,
    "key": "4a5bc52e6763795e18b69bd82dd23a9e",
    "name": "rexshi"
  },
  "time": 1493895236
}
问题类型
{
  "type": "type",
  "action": "update",
  "field": "name",
  "affected": "2d05d57e5fa9bc13f382490d7fee366e",
  "data": {
    "key": "2d05d57e5fa9bc13f382490d7fee366e",
    "name": "注册"
  },
  "project": {
    "key": "83b17e3d158ae72518a19f7de9ce61e7",
    "name": "小测测",
    "description": "测试测试hahah",
    "creator": {
      "role": 4,
      "key": "4a5bc52e6763795e18b69bd82dd23a9e",
      "name": "rexshi"
    },
    "recycled": 0,
    "created": 1462767369
  },
  "sender": {
    "role": 4,
    "key": "4a5bc52e6763795e18b69bd82dd23a9e",
    "name": "rexshi"
  },
  "time": 1494245497
}

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

  1. 用户登录 Tracup
  2. 注册并登录
  3. 点击某个项目,然后点击头部菜单中的「设置」
  4. 在「设置」页面中,找到「Webhook」
  5. 点击「创建 Webhook」
  6. 填写以下内容:
    1. 名称(随便起一个名字,一般可以用第三方服务名称,例如 Slack)
    2. URL(填写第三方服务提供的 Webhook 接收 URL)
    3. 校验密钥(用于校验来源是否正确。如果第三方 Webhook 服务要求时则填写,否则可以不填)
  7. 点击确定

技术支持

如果有任何问题,可以发邮件给我们: service@pgyer.com