审批事件

配置事件订阅

钉钉会向应用推送订阅的事件，例如部门变更、签到通知、打卡通知等。通过订阅这些事件，可以更好地与钉钉集成。你只需告诉钉钉当某个事件发生时，钉钉需要推送消息到哪个URL，钉钉会以HTTP POST请求的方式将事件内容以JSON格式推送给你。

事件订阅流程

事件订阅的流程如下图所示。

首先，开发者需要在钉钉开放平台配置HTTP请求接收地址用于接收推送的订阅事件，然后设置要订阅的事件。在配置完请求地址后，钉钉开放平台会向该地址发送POST请求，只有在规定时间内正确返回了包含"success"的加密字符串才完成事件订阅。

配置请求地址和事件订阅

1. 登录开发者后台，找到已创建的企业内部应用。
2. 单击事件订阅，然后单击编辑配置用于接收请求的HTTP地址。

   注意

   确保该地址公网可以访问。

   

   编辑完请求地址，单击保存按钮时，开放平台会向你配置的网址推送一个 application/json 格式的 POST 请求, 用于验证你配置的网址的合法性。请求如下：

   {

   "encrypt": "ajls384kdjx98XX" // 加密字符串，解密方法请看下方的消息加解密

   }

   当你收到开放平台的POST验证请求时，你需要做解密处理，并在1500ms内返回包含success的加密字符串（JSON格式）。钉钉开放平台收到返回的JSON信息后会做解密处理，如果可以得到正常的success字符串，则验证回调信息推送正常，否则会判定为失败的回调信息。

3. 成功配置请求地址后，在事件订阅列表区域，开启要订阅的事件。

   

接收并响应事件

• 接收事件信息

  当事件发生时，钉钉会主动向配置的HTTP地址发送POST请求，推送对应的事件信息。例如订阅通讯录事件后，当通讯录发生变更时，会向注册的HTTP地址推送事件信息，其格式如下。

  说明

  钉钉服务器推送信息是即时推送，如果企业的回调地址没有在1500毫秒内返回正确的加密信息给钉钉服务器，钉钉服务器会判断为推送失败。

  请求的URL格式如下：

  http://你注册的HTTP地址?signature=111108bb8e6dbc2xxxx&timestamp=1783610513&nonce=380320111

  包含的JSON数据如下：

  {

  "encrypt":"1ojQf0NSvw2WPvW7LijxS8UvISr8pdDP+rXpPbcLGOmIBNbWetRg7IP0vdhVgkVwSoZBJeQwY2zhROsJq/HJ+q6tp1qhl9L1+ccC9ZjKs1wV5bmA9NoAWQiZ+7MpzQVq+j74rJQljdVyBdI/dGOvsnBSCxCVW0ISWX0vn9lYTuuHSoaxwCGylH9xRhYHL9bRDskBc7bO0FseHQQasdfghjkl"

  }

  其中：

  • signature为消息体签名。
  • timestamp为时间戳。
  • nonce为随机字符串。
  • encrypt为加密的推送事件信息。
• 响应事件信息

  当你收到开放平台的POST验证请求时，你需要做解密处理，并在1500ms内返回包含success的加密字符串（JSON格式）。钉钉开放平台收到返回的JSON信息后会做解密处理，如果可以得到正常的success字符串，则验证回调信息推送正常，否则会判定为失败的回调信息。

  具体返回给钉钉的数据格式如下：

  注意

  返回的数据格式必须是JSON格式。

  {

  "msg_signature":"111108bb8e6dbce3c9671d6fdb69d1506xxxx",

  "timeStamp":"1783610513",

  "nonce":"123456",

  "encrypt":"1ojQf0NSvw2WPvW7LijxS8UvISr8pdDP+rXpPbcLGOmIxxxx"

  }

  其中：

  • msg_signature为消息体签名。
  • timeStamp为时间戳。
  • nonce为随机字符串。
  • encrypt为success加密字符串。

消息加解密

为了保证数据传输的安全，钉钉在推送订阅事件时，会携带配置的token用来验证事件来源。同时使用该密钥对消息内容做对称加密。

单击这里获取回调加解密类库和对应demo。

钉钉服务器会把msg消息体明文编码成encrypt。encrypt = Base64_Encode(AES_Encrypt[random(16B) + msg_len(4B) + msg + $key])是对明文消息msg加密处理后的Base64编码。其中：

• random为16字节的随机字符串。
• msg_len为4字节的msg长度，网络字节序。
• msg为消息体明文。
• key为应用的appKey。

取出返回的JSON中的encrypt字段：

• 对密文BASE64解码：aes_msg=Base64_Decode(encrypt)；
• 使用AESKey做AES解密：rand_msg=AES_Decrypt(aes_msg)；

审批事件类型

审批实例开始

示例：

{

"EventType": "bpms_instance_change",

"processInstanceId": "ad253df6-e175caf-xxxxxxxxxxxx",

"corpId": "corpidxxxxxxxxxxxxx",

"createTime": 1495592259000,

"title": "自测-1016",

"type": "start",

"staffId": "er5875",

"url": "https://aflow.dingtalk.com/dingtalk/mobile/homepage.htm",

"processCode":"Pro-xxx"

}

参数说明：

审批实例结束|终止

示例：

{

"EventType": "bpms_instance_change",

"processInstanceId": "ad253df6-e175caf-xxxxxxxxxxxx",

"finishTime": 1495592305000,

"corpId": "dinge8a56572f80b02a8ffexxxx",

"title": "自测-1016",

"type": "finish",

"url": "https://aflow.dingtalk.com/dingtalk/mobile/homepage.htm?corpid=ding2c015874d817xxxx&dd_share=",

"result": "refuse",

"createTime": 1495592272000,

"staffId": "manager75",

"processCode":"Pro-xxx"

}

参数说明：

审批任务开始

示例：

{

"EventType": "bpms_task_change",

"processInstanceId": "ce133dd0-5b22-9516-xxxxxxxxxxxx",

"corpId": "corpidxxxxxxxxxxxxx",

"createTime": 1495593189000,

"title": "自测-1016",

"type": "start",

"staffId": "manager75",

"processCode":"Pro-xxx"

}

参数说明：

审批任务结束

示例：

{

"EventType": "bpms_task_change",

"processInstanceId": "ce133dd0-5b22-9516-xxxxxxxxxxxx",

"finishTime": 1495605749000,

"corpId": "corpidxxxxxxxxxxxxx",

"title": "自测-1016",

"type": "finish",

"result": "refuse",

"remark": "拒绝理由",

"createTime": 1495593189000,

"staffId": "manager75",

"processCode":"Pro-xxx"

}

参数说明：

审批任务转交

示例：

{

"EventType": "bpms_task_change",

"processInstanceId": "439bda1c-d9-9d67-xxxxxxxxxxxx",

"finishTime": 1495542282000,

"corpId": "corpidxxxxxxxxxxxxx",

"title": "自测-2017",

"type": "finish",

"result": "redirect",

"createTime": 1495541847000,

"staffId": "08058646137",

"processCode":"Pro-xxx"

}

参数说明：