交易结果异步回调通知

应用平台方可通过该服务来接收 AVATA 平台主动推送的上链交易结果异步通知消息。

操作流程

1. 登录 AVATA 服务平台
2. 在项目管理页 - 更多操作项中，点击「设置回调地址」，输入您的上链交易结果异步推送回调地址；
   
   或者在项目管理页中，点击编辑，输入您的上链交易结果异步推送回调地址。

注意：需保证回调地址能够被外网访问

3. 设置成功后，AVATA 平台会将您每次接口请求上链的交易结果信息推送至设置好的地址。
4. 单笔交易推送失败，触发重试机制，重新推送 4 次，时间间隔为 1、3、5、10 分钟。
5. 成功接收到请求后，需要返回字符串 SUCCESS。(区分大小写)

回调推送

触发回调行为时，AVATA 平台会发送回调消息到您设置的服务回调地址中，请求内容如下：

• 请求方式：POST

• Header Parameters ( V1 版本)：

参数	类型	说明
X-Api-Key	string	项目 API Key
X-Signature	string	API 签名，算法为 SHA256 (Params+ApiSecret)

• 推送参数( V1 版本)：

{
    "operation_id":"string",                 // 操作 ID
    "type": "string",                        // 用户操作类型
    "module": "string",                      // 交易模块
    "tx_hash": "string",                     // 交易哈希
    "status": 0,                             // 交易状态，1 成功; 2 失败
    "message": "string",                     // 交易失败的错误描述信息
    "block_height": 0,                       // 交易上链的区块高度
    "timestamp": "string",                    // 交易上链时间（UTC 时间）
    "nft": "{                                // 对应不同操作类型的消息体 （参数值为：json字符串）
         "class_id": "string"
         "nft_id": "string",
    }",
     "mt": "{                                // 对应不同操作类型的消息体（参数值为：json字符串）
         "class_id": "string"
         "mt_id": "string",
    }",
     "record": "{                            // 对应不同操作类型的消息体（参数值为：json字符串）
         "record_id": "string",              // 区块链存证 ID
         "certificate_url": "string"         // 区块链存证证书的下载链接；证书下载链接并非长期有效，请您尽快将证书文件下载至本地并妥善保管。
    }"
}

• Header Parameters ( V2 & V3 版本)：

参数	类型	说明
X-Api-Key	string	项目 API Key
X-Signature	string	API 签名，与 网关鉴权签名 方式保持一致
X-Timestamp	string	时间， 1642065511000

• 推送参数( V2 & V3 版本)：

{
    "operation_id":"string",                 // 操作 ID
    "module": 0,                             // 交易模块
    "operation": 0,                          // 用户操作类型
    "tx_hash": "string",                     // 交易哈希
    "status": 0,                             // 交易状态，1 成功; 2 失败
    "message": "string",                     // 交易失败的错误描述信息
    "block_height": 0,                       // 交易上链的区块高度
    "timestamp": "string,                    // 交易上链时间（UTC 时间）
    "nft": {                                 // 对应不同操作类型的消息体（参数值为：json 结构体）
         "class_id": "string",
         "id": "string"                      // 服务为 native 时，id 为字符串，服务为 evm 时，id 为 int
    },
    "mt": {                                  // 对应不同操作类型的消息体（参数值为：json 结构体）
         "class_id": "string"，
         "mt_id": "string"
    },
    "record": {                              // 对应不同操作类型的消息体（参数值为：json 结构体）
         "record_id": "string",              // 区块链存证 ID
         "certificate_url": "string"         // 区块链存证证书的下载链接；证书下载链接并非长期有效，请您尽快将证书文件下载至本地并妥善保管。
    },
    "kind": "string"                         // 区分服务,native/evm
}

回调验签

• v1 版本验签：

  签名 = sha256 (body + api_secret)
  将接收到的 body 转换成 json 字符串，拼接上 api_secret ,进行 sha256 计算。可参考网关鉴权签名示例中的 sha256 的计算方法。

       JSONObject jsonStr = JSON.parseObject("body参数");
       String jsonStr1 = JSON.toJSONString(jsonStr, SerializerFeature.MapSortField);
        // 执行签名
        String signature = sha256Sum(jsonStr1 + "api_secret");
  

• v2 & V3 版本验签：

  签名 = signRequest (“回调地址(去掉域名)”,null,Map<string,object> body,推送的请求头中的时间戳 (Long型),“apisecret”);

tip: 在接收到body后，需要调整部分参数类型为int型，在转换为body进行签名。否则无法验签通过。

回调验签示例 (java)

public String huidiao(HttpServletRequest request, HttpServletResponse response,@RequestBody String data) throws Exception{
        String timestamp =  request.getHeader("X-Timestamp");
        String qianming = request.getHeader("X-Signature");
        // //v1 版本验签
        // JSONObject jsonStr = JSON.parseObject("data");
        // String jsonStr1 = JSON.toJSONString(jsonStr, SerializerFeature.MapSortField);
        // // 执行签名
        // String signature = sha256Sum(jsonStr1 + "api_secret");
        // if(!signature.equals(qianming)){
        //     return "failed";
        // }
        // Map map = new HashMap<>();//map是data转换成json格式后将数据组装到map中
        // //v2 v3 版本验签
        // String signature=signRequest("设置的回调地址去掉域名", null, map, Integer.valueOf(timestamp), "api-secret");
        // if(!signature.equals(qianming)){
        //         return "failed";
        //     }
            return "SUCCESS";
    }

地址无法接收到回调

• 请检查设置的地址是否能够被外网访问。
• 请检查是否正确接收到回调信息。（建议接收 body、header 两个部分内容）
• 如果使用代理等配置（包括但不限限于问题），请检查确保能够成功请求到这个地址。
• 如果有设置白名单配置：
  • 正式环境：69.234.228.106
  • 测试环境：101.132.149.235、139.196.57.84 、47.101.67.19 、106.15.57.49