变更记录

1 介绍

开放事件订阅时，要求第三方系统提供一个可直接访问的Webhook回调接口，当事件触发时，系统会调用该接口向第三方系统传递事件消息。下面是平台对回调接口要求。

为保障数据传输安全，防止传输过程中数据被篡改和泄露，从V6.0.13版本开始，开放事件支持签名和加密。用户可以在事件订阅推送页面配置签名(页面必选，对接方也可不验签)和加密(可选)策略，操作详情见 事件推送订阅 ，平台在推送事件前会根据配置进行请求签名和数据加密。回调接口需要实现对应的验签和解密算法才能拿到事件数据。

事件触发时序图

2 回调接口协议

支持http/https协议。

3 请求说明

3.1 请求方式

POST+ application/json

3.2 请求参数

 请求头（Header)

请求体-加密报文

参数示例：

{"encrypt":"TgwQHnE78p83RiqIiuPSyMSjv89Aj0MBhvcd5Pq3mIXxpwF4YWOi/TARaDnAo0WkgATJwl5p13KznUKJJ25NDQylO3VebDsIXuN3hvS93qb2v6gkDuF9IaEDOUdOBxJhYJKcfX2o3wvAU84lfqH4F8yqLOGsSsljUvNKeWKpEPBgpn/+ZDS3v+K9Gi8cF0Ix5A/DMeBLkqO5sJQuuPb5ni5W7YLEfZrPMQh1r2BcaKqJ8wUrz6e8ZyfAGJ4s38OMIzEflHdX5FHjsQNJ4CgqsnUHAynE4nZRhBYrVLiVba3SBqqr+Fw8H3OaAuN0G5RijCyItrOUtG20z9UFEPF+LqGJ9XqroAGUJ0ijK0V9jTb0ExEibNxjCtYMGzthbMOo"}

注意：加密是对整个消息体做的加密。

请求体-不加密或解密报文

参数示例：

{
    "data":{
        "id":"1858013541517285376",
        "number":"eeee",
        "name":"eeee",
        "enable":"1",
        "status":"C",
        "remark":"",
        "creator":"1754371843654946816",
        "createtime":"2024-01-08 13:41:07.472",
        "modifytime":"2024-01-08 13:41:14.326",
        "modifier":"1754371843654946816"
    },
    "eventNumber":"kdtest.kemopenevt.osc.open.sortdelete",
    "msgId":"1858013636274991104",
    "entityNumber":"openapi_custom_sort",
    "operation":"save"
}

 4 验签说明

从V6.0.13版本后，所有开放事件推送必须进行请求签名，确保回调地址收到的请求来至于可信的源。用户可在事件订阅推送页面配置签名策略和签名密钥，签名策略支持HMAC_SHA_256和SHA_256两种。请根据页面配置的签名策略和密钥，使用对应的算法进行签名计算。

注意：V6.0.13版本后，开放事件推送时必须加签，所以订阅页面必须配置签名策略和密钥，对接方可选择验签或不验签，都不影响事件参数传递，但建议对接方做验签处理，避免传输过程中数据被篡改。

4.1 验签过程

1、从请求中获取如下参数

• timestamp：时间戳，获取请求头中的 x-kem-request-timestamp。

• nonce：数据数，获取请求头中的 x-kem-request-nonce。

• signature：消息签名，获取请求头中的  x-kem-signature。

• body：接收的请求体。

2、订阅推送页面设置的签名密钥 signsecretkey；

3、组装签名内容：signsecretkey + timestamp + nonce + body；

4、用订阅推送页面配置的签名算法对签名内容进行签名；

5、将签名结果转为16进制字符串，并与请求头中 x-kem-signature 签名内容进行比较是否一致。

4.2 Java示例代码

以 HMAC_SHA_256为例：

public String calculateSignature(String signsecretkey, String timestamp, String nonce, String bodyString) throws NoSuchAlgorithmException, InvalidKeyException {
   String content = signsecretkey + timestamp + nonce + bodyString;
   
   Mac hmacSHA256 = Mac.getInstance("HmacSHA256");
   SecretKeySpec secretKeySpec = new SecretKeySpec(signsecretkey.getBytes(StandardCharsets.UTF_8), "HmacSHA256");
   hmacSHA256.init(secretKeySpec);

   byte[] signData = hmacSHA256.doFinal(content.getBytes(StandardCharsets.UTF_8));

   return Hex.encodeHexString(signData);

}

5 解密说明

为防止数据传输过程中泄露，从V6.0.13版本后，支持对推送的事件消息进行数据加密。用户可在事件订阅推送页面配置加密策略和加密密钥，对接时根据配置进行数据解密。事件传输加密为非必须，可根据数据安全要求自行选择。

支持的加密策略如下：

5.1 解密过程

1、获取请求体加密报文 encrypt；

2、获取请求头中的初始向量 x-kem-encrypt-iv；

3、使用Base64解码 encrypt，即为加密数据encrypted_data；

4、使用Base64解码请求头 x-kem-encrypt-iv 的值，即为初始向量iv；

5、用订阅推送页面配置的加密算法，使用初始向量 iv 和页面配置的加密密钥 encryptsecretkey 对加密数据encrypted_data进行解密，将解密结果转为字符串即为请求体的解密报文。

5.2 Java示例代码

以AES/CBC/PKCS5Padding算法为例：

public String decrypt(String encrypt, String encryptsecretkey, String ivStr) throws Exception {
   Cipher cipher = Cipher.getInstance("AES/CBC/PKCS5Padding");
   byte[] key = Base64.decodeBase64(encryptsecretkey);
   byte[] data = Base64.decodeBase64(encrypt);
   // 获取iv
   byte[] iv = Base64.decodeBase64(ivStr);
   SecretKeySpec keySpec = new SecretKeySpec(key, "AES"); // 或 SM4
   AlgorithmParameterSpec paramSpec = new IvParameterSpec(iv);
   cipher.init(Cipher.DECRYPT_MODE, keySpec, paramSpec);

   return new String(cipher.doFinal(data), StandardCharsets.UTF_8);
}

6 返回要求

6.1 返回结构

Json

6.2 返回参数

平台根据返回结果判断回调地址请求是否成功，返回结果不需要进行加密和签名。

参数说明

参数示例：

{
    "status":true
}

7 超时和重试

1、回调接口需确保在3s内返回，如果3s不返回则认为超时失败。

2、事件推送订阅默认配置重试3次，即首次推送失败后系统会重复推送3次，对接方需要确保回调接口请求的可重试性，避免出现业务重复处理。

3、如果重试3次依然失败，系统不再重试。后续可前往推送日志列表进行手工重试。

8 兼容性说明

V6.0.13版本之前配置的事件订阅推送数据，在平台版本升级后，运行时还会按照无签名和无加密的方式继续正常推送事件消息。