配置SyncHTTP推送

SyncHTTP推送方式适用于本地部署的情况。与HTTP推送方式比，SyncHTTP推送的是业务数据的最终状态，开发者可以直接使用推送的数据。

回调说明

钉钉会向第三方企业应用推送订阅的回调事件，包括应用开通、应用授权变更、部门变更等。通过订阅这些事件，开发者可以更好地与钉钉集成。

第三方企业应用开发必须要注册回调，接收企业授权开通应用事件，用于通知三方应用哪个组织开通了本应用，第三方应用后台收到此事件后，需要初始化企业信息。

钉钉目前支持的推送方法有：

RDS推送

HTTP推送

SyncHTTP推送

SyncHTTP是按RDS推送的字段和格式将数据以HTTP回调的方式推送到ISV的服务。服务商可将HTTP接收的数据，按照RDS推送方式和类型保存到自建数据库或RDS中。

说明

SyncHTTP接收到回调后需要马上保存到数据库中，然后返回成功，如需处理其他业务逻辑，请使用异步处理。

SyncHTTP不需要开发者手动调用激活应用接口，接到推送ticket后可用其直接调用服务端接口。

说明

SyncHTTP推送和HTTP推送的出口IP为203.119.0.0/16 140.205.0.0/16 106.11.0.0/16 198.11.0.0/16。

注册回调事件流程

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

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

配置请求地址和订阅回调事件

通过SyncHTTP回调方式接收钉钉推送的回调事件，首先需要配置HTTP回调URL。当应用订阅的事件触发时，钉钉会向该网址发送相应的 HTTP POST 请求。

登录开发者后台。找到已创建的应用，进入应用详情页。

单击开发管理，然后单击修改，推送类型选择SyncHTTP推送。

配置用于接收请求的HTTP地址。

token：钉钉每次向你的地址推送事件数据时都会携带token，用于生成签名、校验回调请求的合法性。必须为英文或数字，长度为3~32个字符。

数据加密密钥：单击自动生成生成AES密钥。回调消息内容的加解密参数，是AES密钥的Base64编码，具体使用参见消息加解密。

回调URL：用于接收订阅事件请求的URL。当应用订阅的事件触发时，钉钉会向该网址发送相应的 HTTP POST 请求。

说明

每个应用只能配置一个回调URL，该应用订阅的所有事件通知都会发送到该请求网址。
p256064

配置完成后，单击验证有效性按钮时，开放平台会向你配置的网址推送一个application/json格式的 POST请求, 用于验证你配置的网址的合法性。如下所示：

{
    "encrypt":"HJ+q6tp1qhl9L1+++j74xxxx"   //加密字符串，参考下文的加解密说明
}

当你收到开放平台的POST验证请求时，你需要做解密处理，并在1200ms内返回包含success的加密字符串给钉钉，长时间未及时响应会被限流。

成功配置请求地址后，在回调事件列表区域，勾选要订阅的回调事件，然后单击右上角保存。

说明

如果某个回调事件无法勾选，在开发者后台的权限管理页面申请对应的接口权限。
p204978

推送数据说明

配置完回调URL后，单击验证有效性按钮时，开放平台会向你配置的网址推送一个application/json格式的 POST请求, 用于验证你配置的网址的合法性。如下所示：

{
    "encrypt":"HJ+q6tp1qhl9L1+++j74xxxx"   //加密字符串，参考下文的加解密说明
}

你需要对收到的消息内容进行解密，详情请参考消息加解密。解密后的事件类型如下：

check_url：测试回调事件

解密后数据：

{
    "EventType" : "check_url"
}

check_create_suite_url：验证回调事件

解密后数据：

{
  "EventType":"check_create_suite_url",
  "Random":"brdkKLMW"
}

check_update_suite_url：回调地址更新事件

解密后数据：

{
  "EventType":"check_update_suite_url",
  "Random":"xxxxxx",
  "TestSuiteKey":"suited6db0pze8yao1b1y"
}

SYNC_HTTP_PUSH_HIGH：高优先级数据，激活应用等

{
 "EventType": "SYNC_HTTP_PUSH_HIGH",
 "bizData": [{
  "gmt_create": 1608639648000,
  "biz_type": 4,
  "open_cursor": 0,
  "subscribe_id": "14999999001_0",
  "id": 7001,
  "gmt_modified": 1608639648000,
  "biz_id": "1489999001",
  "biz_data": "{\"auth_user_info\":{\"userId\":\"manager4xxx\"},\"auth_corp_info\":{\"corp_type\":0,\"corpid\":\"dingffea2a0dcc37d0xxxxxxx25e91351\",\"auth_level\":0,\"auth_channel\":\"\",\"industry\":\"\",\"full_corp_name\":\"xx测试组织\",\"corp_name\":\"xx测试组织\",\"invite_url\":\"https://pre-wx.dingtalk.com/xxxxx/index.html?bizSource=____source____&corpId=dingffea2a0dcc3xxxxx25e91351&inviterUid=71E7E5B48C2DDB2xxxxxxF52346D\",\"auth_channel_type\":\"\",\"invite_code\":\"\",\"is_authenticated\":false,\"license_code\":\"\",\"corp_logo_url\":\"\"},\"syncAction\":\"org_suite_auth\",\"auth_scope\":{\"errcode\":0,\"condition_field\":[],\"auth_user_field\":[\"jobnumber\",\"isLeader\",\"name\",\"position\",\"isAdmin\",\"avatar\",\"department\",\"userid\",\"deviceId\",\"isHide\"],\"auth_org_scopes\":{\"authed_user\":[],\"authed_dept\":[1]},\"errmsg\":\"ok\"},\"auth_info\":{\"agent\":[{\"agentid\":1038226450,\"agent_name\":\"土壕推送测试1217\",\"logo_url\":\"https://static-legacy.dingtalk.com/media/lADPDfmVQafoVxxxxxx0_200.jpg\",\"appid\":62282,\"admin_list\":[\"manager492\"]}]},\"permanent_code\":\"MFcbac-7zg0Mhcl-_dGmY2_f4NZPzLUf813xxxxxrjyEoGmKjqZwfi-5mh\"}",
  "corp_id": "dingffea2axxxxxx0dcb25e91351",
  "status": 0
 }]
}

SYNC_HTTP_PUSH_MEDIUM：普通优先级数据，例如通讯录变更

{
 "EventType": "SYNC_HTTP_PUSH_MEDIUM",
 "bizData": [{
  "gmt_create": 1608639751000,
  "biz_type": 14,
  "open_cursor": 0,
  "subscribe_id": "14778001_0",
  "id": 68,
  "gmt_modified": 1608639751000,
  "biz_id": "433877002",
  "biz_data": "{\"errcode\":0,\"userPermits\":\"\",\"userPerimits\":\"\",\"syncAction\":\"org_dept_create\",\"outerDept\":false,\"errmsg\":\"ok\",\"deptManagerUseridList\":\"\",\"parentid\":1,\"groupContainSubDept\":false,\"outerPermitUsers\":\"\",\"outerPermitDepts\":\"\",\"deptPerimits\":\"\",\"createDeptGroup\":true,\"name\":\"f'f'f\",\"id\":433885002,\"autoAddUser\":true,\"deptHiding\":false,\"deptPermits\":\"\",\"order\":43388775002}",
  "corp_id": "ding7629a25dxxxxxxxxf7214b6d69",
  "status": 0
 }]
}

SYNC_HTTP_PUSH_HIGH和SYNC_HTTP_PUSH_MEDIUM类型的bizData数据就是RDS推送中的open_sync_biz_data和open_sync_biz_data_medium表中的数据，具体格式请参数据格式。

接收并响应回调事件

启动一个HTTP服务（如下所示），在服务响应逻辑中解密后存储回调（推送）数据。

完整代码示例：https://github.com/opendingtalk/eapp-isv-quick-start-java/blob/master/src/main/java/com/controller/CallbackController.java

消息加解密

为了保证数据传输的安全，钉钉在向回调URL推送订阅的回调事件时，会携带配置的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为应用的suiteKey。

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

对密文BASE64解码：aes_msg=Base64_Decode(encrypt)；

使用AESKey做AES解密：rand_msg=AES_Decrypt(aes_msg)；

加解密代码示例如下，完整示例请参见钉钉第三方企业应用-小程序-快速开始Java版：

说明

此代码示例的加解密过程依赖DingCallbackCrypto工具类，参见dingtalk-callback-Crypto。

回调说明#

注册回调事件流程#

配置请求地址和订阅回调事件#

推送数据说明#

接收并响应回调事件#

消息加解密#

回调说明

注册回调事件流程

配置请求地址和订阅回调事件

推送数据说明

接收并响应回调事件

消息加解密