Callback通知

概述

本文档主要面向需要主动推送通知的客户，并协助客户完成相关系统开发。

约定

您需要在您的云服务器上提供符合以下约定的 API，并在您的服务器上实现业务逻辑。

• 回调通知仅支持POST方法，并且Content-Type=application/json。
• 请参考本部分的其他子章节以了解不同业务的通知。

注意：

• 发送到您服务器的通知请求主体数据通常与手动调用相应业务查询 API 时响应主体中的 data 属性相同。

通知规则

当相应的任务完成后，Clobotics会把相应的结果信息发送给客户，客户需要接收处理该消息，并返回应答。

Callback通知时，如果Clobotics收到客户的应答不符合规范或超时(超时时间10s)，Clobotics认为通知失败，Clobotics会通过一定的策略定期重新发起通知，尽可能提高通知的成功率，但不保证通知最终能成功。重试的总次数为3次（不包含第一次通知），策略为30s/5m/0.5h。

注意：

• 如果最终的重试通知失败，客户端可以主动调用指定的查询接口来检索任务结果。

应答规则

接收成功

如果您的云服务器成功接收到我们的通知，请返回 200的HTTP状态码 。如果 HTTP 状态码为 200，则不会验证响应主体。

接收失败

如果您的服务器未能正确处理我们的通知或遇到网络问题，请返回 4xx 或 5xx 的 HTTP 状态码，同时返回的响应主体请包含错误信息。返回格式如下所示：

{
  "code": "-1",
  "message": "error msg"
}

参数名	类型	说明
code	string	返回的code码，字符长度最长36位
message	string	返回的错误信息，字符长度最长200位

通知验证

为了增强系统安全性并防止攻击，Clobotics会在通知的HTTP头部中包括通知报文的签名。建议客户验证通知的签名，以确保通知是由Clobotics发送。

注意：

• 客户可以选择是否验证签名。如果选择不验证，则系统安全性会降低。

构造签名串

客户需要先从请求中获取以下信息：

• Timestamp：HTTP头中key=Timestamp的时间戳。
• Nonce：HTTP头中key=Nonce的随机字符串。
• Body：请求的报文。需要按照接口返回的原始数据进行验签，随意调整原始数据将会导致验签失败。

然后，请按照以下规则构造应答的验签字符串StringToSign。

StringToSign = Content-MD5 + "\n" + Timestamp + "\n" + Nonce

• Content-MD5为应答报文的Base64(MD5(Body))，MD5(Body)为MD5后的字节流，不需要进行hex。
• Timestamp为前一步获取的值。
• Nonce为前一步获取的值。

注意：

• \n 表示换行符，Content-MD5、Timestamp等连接顺序的序列不能随意更改。
• 不要随意调整StringToSign的拼接顺序；否则，签名验证将失败。

获取应答签名

Clobotics的通知签名通过HTTP头Authorization传递。

Authorization的格式如下：

Authorization: cbs:APPID:Signature

• cbs：为固定前缀。
• APPID：提交信息时使用的APPID。
• Signature：此次通知的签名。

注意：

• 各字符以英文:隔开。

验证签名

签名的计算公式如下：

Signature = Base64(HMAC-SHA256(APPSECRET, StringToSign))

StringToSign为前面拿到的构造签名串，APPSECRET为信息提交时所使用APPID对应的密钥。

比对计算拿到的Signature与HTTP头中Authorization对应的Signature，如果值相等，则验签通过，否则验签失败。

注意：

• APPID和APPSECRET是向我们的OpenAPI系统提交请求时使用的一对相同的凭证。

通知示例

假如提交任务时的APPID=85206f97-2f4f-4b6e-8830-f3f4ec6fd6ae，对应的APPSECRET=c6ae8924a68a5d839947a7885894dfe4。

通知报文如下

Content-Type: application/json
Content-Length: 2204
Connection: keep-alive
Content-Language: zh-CN
Nonce: c5ac7061fccab6bf3e254dcf98995b8c
Authorization：cbs:85206f97-2f4f-4b6e-8830-f3f4ec6fd6ae:RHHlRHs+Jkez/KmMzzK+zE6RRrmYCENwV4LsEUuO+4k=
Timestamp:1676764711

{"request_id":"9177er67378273888287321","image_url":"https://f-dev.clobotics.cn/4/0040ca4d85f5e5ef7354102f486ef843.jpg","scene_type":"104","ext_info":"this is a test"}

• 计算请求Body的Content-MD5

Content-MD5=ilHp6H9FaX49IFrwOj/TDw==

• 组成stringToSign

ilHp6H9FaX49IFrwOj/TDw==
1676764711
c5ac7061fccab6bf3e254dcf98995b8c

• 计算签名

Signature=RHHlRHs+Jkez/KmMzzK+zE6RRrmYCENwV4LsEUuO+4k=

• 对比

根据上一步得到的Signature，如果它与请求中Authorization按:分割后的第三部分相等，则表示签名验证已通过。