Webhook接口设计

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 示例）

4.2 data的数据格式

• 当配置 webhook 时的类型为”预警”(即 type == “warning”)时：
  • 发送成功消息时，传除了 errMsg 之外的所有参数，
  • 发送失败消息时，传带星号的参数，
  • 消息类型取决于 msgStatus 字段。

• 当配置 webhook 时的类型为”定时推送”(即 type == “report”)时：
  • 发送成功消息时，传除了 errMsg 之外的所有参数，
  • 发送失败消息时，传带星号的参数，
  • 消息类型取决于 msgStatus 字段。

• 当配置 webhook 时的类型为”取数”(即 type == “easyFetch”)时：
  • 发送成功消息时，传除了 errMsg 之外的所有参数，
  • 发送失败消息时，传带星号的参数，
  • 消息类型取决于 msgStatus 字段。

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