Callback Notification

Overview

This document is primarily intended for clients requiring active push notifications, assisting in the completion of related system development.

Conventions

You need to provide an API on your cloud server that adheres to the following conventions and implement the business logic on your end.

• Callback notifications exclusively use POST method with Content-Type=application/json.
• Refer to the subsections of this section to retrieve different notifications.

Notes:

• The notification request body data sent to your server is generally the same as the data attribute in the response body when you manually call the corresponding business query API.

Notification Rules

When the corresponding task is completed, Clobotics sends the result information to the client, which is expected to receive, process the message, and return a response.

During Callback notification, if Clobotics receives a response from the customer that does not meet the specifications or timeout (the timeout period is 10s), it considers the notification a failure. Clobotics will then periodically re-send the notification using a specific strategy to maximize success. However, success is not guaranteed, and there are a total of 3 retry attempts (excluding the initial notification) with intervals of 30s/5m/0.5h.

Notes:

• If the final retry notification fails, the client can proactively call the designated query interface to retrieve the task result.

Response Rules

Receive Successfully

If your cloud server successfully receives our notification, please return an HTTP status code of 200. If the HTTP status code is 200, the response body will not be verified.

Receive Failed

If your cloud server fails to process our notification or encounters a network issue, we may receive an HTTP status code with 4xx or 5xx. If you send a response back, please include error information. The schema is as follows:

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

Parameter	Type	Description
code	string	Response code，the character length is up to 36 characters
message	string	Response error message, the maximum length is 200 characters

Notification Verification

To enhance system security and prevent attacks, Clobotics will include the signature of the notification message when requesting the callback_url with the appropriate request header and body. We strongly recommend verifying the signature of the notification request data to ensure that the notification is sent by Clobotics.

Notes:

• Clients can choose to verify the signature or not. If you choose not to, the system will have lower security.

Construct Signature String

Clients need to retrieve the following information from the request:

• Timestamp: The timestamp is obtained from the HTTP request header key Timestamp.
• Nonce: A random string obtained from the HTTP request header key Nonce.
• Body: The request body. Signature verification should be performed based on the original data returned by the interface, and randomly altering the original data will result in signature verification failure.

Next, construct the response signature verification string StringToSign according to the following rules:

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

• Content-MD5 is the Base64(MD5(Body)) of the response message. MD5(Body) is the byte stream after MD5 and does not need to be hexed.
• Timestamp is the value obtained in the previous step.
• Nonce is the value obtained in the previous step.

Notes:

• \n represents a newline character, and the sequence of concatenation for Content-MD5, Timestamp etc. cannot be altered arbitrarily.
• Do not arbitrarily adjust the splicing sequence of StringToSign; otherwise, the signature verification will fail.

Get Signature from Authorization

Clobotics notification signatures are transmitted through the HTTP header key Authorization in the request body.

The value of Authorization follows this format:

Authorization: cbs:APPID:Signature

• cbs: a fixed prefix.
• APPID: APPID used when submitting information.
• Signature: Signature for this notification.

Notes:

• Each part is separated by :.

Verify Signature

The signature calculation formula is as follows:

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

Here, StringToSign is the constructed signature string obtained in Construct Signature String.

Compare the calculated Signature with the Signature in the Authorization HTTP header. If the values are equal, the signature verification will pass; otherwise, the signature verification will fail.

Notes:

• APPID and APPSECRET is the same pair when you submit requests to our OpenAPI system.

Notification Sample

For example,

APPID=85206f97-2f4f-4b6e-8830-f3f4ec6fd6ae

APPSECRET=c6ae8924a68a5d839947a7885894dfe4.

The raw request for the notification is as follows:

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"}

• Calculate the Content-MD5 of the request Body

Content-MD5=ilHp6H9FaX49IFrwOj/TDw==

• Compose StringToSign

ilHp6H9FaX49IFrwOj/TDw==
1676764711
c5ac7061fccab6bf3e254dcf98995b8c

• Calculate signature

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

• Do the comparison

The Signature obtained in the previous step is equal to the third part of the Authorization in the request when split by :, so the signature verification has passed.