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 调用结果。