Webhook接口设计
更新时间: 2022-12-05 16:57:47
阅读 5108
1.概述
- 需根据本产品的规范,对每个添加的 webhook 地址,实现一个 get 请求接口和一个 post 请求接口。
- Get 请求用于:本产品验证 webhook 接口可用性。
- Post 请求用于:本产品调用进行消息推送。
2. 配置参数
- name(String):webhook 的名字。
- url(String):webhook 的请求地址。
- secret(String):用于使 webhook 验证本产品有效性。
- type(String):webhook 类型,”warning”、”report”、”easyFetch”中的一个,分别表示”预警”、”定时推送”、”取数”。
- custom(Object):用户自定义参数。本产品调用 webhook 时会把它放在请求体 body 中一起传。
3. 验证 webhook url 有效性
本产品在通过该验证后,才会把对应的 webhook 添加到系统中。Get 请求,url 为用户配置的 http(s)://host。
- 请求地址及参数:
- 请求地址:http(s)://host?timestamp=TIMESTAMP&nonce=NONCE&signature=SIGNATURE
- timestamp(long):调用 webhook 时的时间戳
- nonce(long):随机数
- signature(String):先对 timestamp,nonce,secret 进行字典序排序后拼接成一个字符串,然后求 sha1 的结果。即
sha1(sort(timestamp,nonce,secret))
。Webhook 端可根据该字段的值判断请求是否来自于本产品(也可以不判断)。示例:
long timestamp = 1583890769246; long nonce = 5111011325335330; String secret = “gzBDV9AMbGfHcf28”; String sortedString = Arrays.sort([timestamp.toString, nonce.toString, secret]) = “15838907692465111011325335330gzBDV9AMbGfHcf28”; String signature = sha1(sortedString) = “6460c444cf9df23a73717d16f7101199e79b8ec2”;
- 返回:
{"code":0,"msg":"ok"}
- content-type:”application/json”
- 本产品使用 code == 0 来判断 webhook 是否有效。
4. 调用 webhook
- 当预警被触发,或者到了设置的定时任务时间,本产品调用 webhook 进行消息推送。
- Post 请求,url 为用户配置的 http(s)://host。
4.1 请求地址及参数
- 请求地址:http(s)://host?timestamp=TIMESTAMP&nonce=NONCE&signature=SIGNATURE 地址中携带的参数含义与上述一致,webhook 端可根据 signature 判断请求是否来自于本产品(也可以不判断)。
- Header
- content-type: “application/json”
- Body(Body 示例)
参数名 | 参数类型 | 参数含义 |
---|---|---|
custom | Object | 用户自定义参数。用户在配置 webhook 时输入 |
from | String | 推送 webhook 的事件名。”warning”表示度量预警,”report”表示定时推送,取数推送到webhook没有该字段 |
receiverList | List | 接收人列表,每个域内接收人的属性有:id,name,phone,email,weChatId,dingTalkId;域外邮箱的属性有:id:-1,email;域外电话的属性有:id:-2,phone;取数推送到webhook没有该字段 |
msgType | String | “text”:文本,此时 data 中不存在 picture 相关信息。“picture”:图片,此时 data 中不存在 abstractDesc 字段。“picture-text”:图片+文本 |
data | Object | 预警或者报告的数据体 |
4.2 data的数据格式
- 当配置 webhook 时的类型为”预警”(即 type == “warning”)时:
- 发送成功消息时,传除了
errMsg
之外的所有参数, - 发送失败消息时,传带星号的参数,
- 消息类型取决于
msgStatus
字段。
- 发送成功消息时,传除了
参数名 | 参数类型 | 参数含义 |
---|---|---|
msgStatus * | String | 消息类型,”success” 或者 “fail” |
warningId * | Int | 触发的预警 id |
warningName * | String | 触发的预警名称 |
componentId * | String | 预警所在图表的 id |
componentName * | String | 预警所在图表的名称 |
dashboardId * | Int | 预警所在 dashboard 的 id |
dashboardName * | String | 预警所在 dashboard 的名称 |
reportId * | Int | 预警所在报告的 id |
reportName * | String | 预警所在报告的名称 |
projectId * | Int | 预警所在项目的 id |
projectName * | String | 预警所在项目的名称 |
abstractDesc * | String | 触发的预警摘要,该字段简要说明触发了预警的数据 |
pictureBase64 | String | 预警对应图表截图使用 base64 编码后的结果 |
pictureMd5 | String | 预警对应图表截图使用 md5 编码后的结果 |
pictureName | String | 截图的名称,包括拓展名”jpeg”、”png”等 |
pictureSize | Int | 截图的大小,单位:字节 |
pictureLink | String | 截图的下载链接 |
coverPictureBase64 | String | 封面图 base64 编码后的结果 |
coverPictureMd5 | String | 封面图使用 md5 编码后的结果 |
coverPictureName | String | 封面图的名称,包括拓展名”jpeg”、”png”等 |
coverPictureSize | Int | 封面图的大小,单位:字节 |
coverPictureLink | String | 封面图的下载链接 |
warningLink * | String | 预警所在的 dashboard 的 url |
flushTime * | Long | 数据刷新的时间戳 |
errMsg * | String | 出错原因及解决方式 |
- 当配置 webhook 时的类型为”定时推送”(即 type == “report”)时:
- 发送成功消息时,传除了
errMsg
之外的所有参数, - 发送失败消息时,传带星号的参数,
- 消息类型取决于
msgStatus
字段。
- 发送成功消息时,传除了
参数名 | 参数类型 | 参数含义 |
---|---|---|
msgStatus * | String | 消息类型,”success” 或者 “fail” |
reportId * | Int | 报告的 id |
reportName * | String | 报告的名称 |
projectId * | Int | 报告所在项目的 id |
projectName * | String | 报告所在项目的名称 |
bodyDesc | String | 推送的正文内容 |
pictureBase64 | String | 报告截图使用 base64 编码后的结果 |
pictureMd5 | String | 报告截图使用 md5 编码后的结果,长度为 32 的字符串 |
pictureName | String | 截图的名称,包括拓展名”jpeg”、”png”等 |
pictureSize | Int | 截图的大小,单位:字节 |
pictureLink | String | 截图的下载链接 |
dashboardData | Arr | 数据表格内容,数组,包含页面id、组件名称、表格数据的二维数组 |
attachmentLink | String | 附件的下载链接 |
coverPictureBase64 | String | 封面图 base64 编码后的结果 |
coverPictureMd5 | String | 封面图使用 md5 编码后的结果 |
coverPictureName | String | 封面图的名称,包括拓展名”jpeg”、”png”等 |
coverPictureSize | Int | 封面图的大小,单位:字节 |
coverPictureLink | String | 封面图的下载链接 |
reportLink * | String | 报告的 url |
errMsg * | String | 出错原因及解决方式 |
- 当配置 webhook 时的类型为”取数”(即 type == “easyFetch”)时:
- 发送成功消息时,传除了
errMsg
之外的所有参数, - 发送失败消息时,传带星号的参数,
- 消息类型取决于
msgStatus
字段。
- 发送成功消息时,传除了
参数名 | 参数类型 | 参数含义 |
---|---|---|
msgStatus * | String | 消息类型,”success” 或者 “fail” |
schemaInfo | Array | 元数据信息,数组元素是对象{name: “列名”,type: “字段类型”} |
lineCount | Int | 文件的行数 |
viewerInfo * | Object | 表示数据来自的阅览者的信息,属性包括 id,uniqueId,phone,email |
fileName | String | 文件名称,不包括拓展名,如”abc” |
fileType | String | 文件类型,如”xlsx”、”csv” |
downloadLink | String | 文件下载的链接。excel下载下来是个xlsx文件;csv下载下来是一个zip文件,解压后里面有一个csv |
msgTag * | String | 唯一标识发送的执行结果 |
errMsg * | String | 出错原因及解决方式 |
4.3 输入示例
示例1
{
"custom": {
"robotUrl": "https://123.com/abc",
"color":{
"r":255,
"g":0,
"b":0
}
},
"receiverList": [{
"id": 1,
"name": "小明",
"phone": "13088888888",
"email": "xiaoming@admin.com",
"weChatId": "XiaoMing",
"dingTalkId": "xiaoming"
}, {
"id": -1,
"email": "xiaohong@admin.com"
}, {
"id": -2,
"phone": "13066666666"
}],
"msgType": "picture-text",
"data": {
"msgStatus": "success",
"warningId": 1,
"warningName": "预警名称",
"componentId": "c-1-128693-136413-k47wa7rj",
"componentName": "图表名称",
"dashboardId": 1,
"dashboardName": "页面1",
"reportId": 1,
"reportName": "报告名称",
"projectId": 1,
"projectName": "项目名称",
"abstractDesc": "东北销售额的求和为 10000,大于 100,触发预警,请及时查看",
"pictureBase64": 'iVxIHEgcSBNuJAEvBt9DFSVRIHEgcSB1rJgSTgW8nNVFbiQOJA4kAbcSAJ+Db6GKkqiQOJA4kDreRAEvCt5GYqK3EgcSBxoI048F8SmkEYgmFzNwAAAABJRU5ErkJggg==',
"pictureMd5":"7b4ed889dea0f24c3abee3bbf2b98607",
"pictureName": "abc.png",
"pictureSize": 512,
"warningLink": "https://netease.youdata.163.com/dash/folder/1?rid=1&did=1",
"flushTime": 1583829855276
}
}
示例2
{
"custom": {
"emails": [
"guochaotong@corp.netease.com"
]
},
"msgType": "easyFetchExport",
"data": {
"msgStatus": "success",
"schemaInfo": [
{
"name": "姓名",
"type": "String"
},
{
"name": "学号",
"type": "Whole"
}
],
"lineCount": 10,
"fileName": "呃",
"fileType": "xlsx",
"downloadLink": "http://nos.netease.com/youdata-test/excel-export-1595407226435.xlsx?Expires=1596767368&NOSAccessKeyId=f3318b2c1f67409386bb99813a44c778&Signature=4lbioAJ4EF5M8In2DNF7jchDdDM3QEQW0Hm2enp%2FKso%3D&download=%E5%91%83.xlsx",
"msgTag": "9d4f0ca6-5574-ef06-f329-69a1b144c12a",
"errMsg": null,
"viewerInfo": {
"id": 11114,
"uniqueId": "guochaotong@corp.netease.com",
"phone": "13088888888",
"email": "guochaotong@corp.netease.com"
}
}
}
dashboardData 示例
dashboardData 是数组,数组中的元素是对象。每个对象都包含 componentTitle、dashboardId、normalSheetData 三个属性。其中,normalSheetData 是二维数组,数组第一项为表头,后面为数据。
[
{
"componentTitle": "折扣(按地区划分)",
"dashboardId": 139357,
"normalSheetData": [
[
"地区",
"折扣"
],
[
"东北",
"234.95"
],
[
"中南",
"234.25"
],
[
"华东",
"333.50"
],
[
"华北",
"74.10"
],
[
"西北",
"53.40"
],
[
"西南",
"134.20"
]
]
}
]
5. 返回
{"code":0,"msg":"ok"}
- content-type:”application/json”
- 本产品使用 code == 0 来判断请求成功。无论成功与否,都可以在系统中查看 webhook 调用结果。
文档反馈
以上内容对您是否有帮助?