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