Receiving Callback

Note

Callback services cannot guarantee complete reliability. Please carefully consider the risks of using callback solutions to build core business processes.

Through this callback, you can monitor information related to digital human video stream tasks, including video stream task status and video stream drive task status.

Callback Description

Request method: POST.
Note
Callback data format is JSON.
Request URL: Please provide the URL of your server for receiving callbacks and contact ZEGOCLOUD technical support for configuration.
Transmission protocol: HTTPS/HTTP, HTTPS is recommended.

Callback Parameters

Note

ZEGOCLOUD will continuously optimize and update the relevant callback parameters in future iteration plans (for example: adding new fields or adding parameter values for certain fields). When developers integrate, please avoid hardcoding to ensure compatibility with new versions after updates.

Parameter	Type	Description
AppId	Number	Unique identifier given by ZEGOCLOUD to your APP.
EventType	Number	Event type. 3: Digital human video stream task status. 4: Digital human video stream task drive status.
Nonce	String	Random number used for signature calculation.
Timestamp	String	Unix timestamp (seconds) when the callback was sent, used for signature calculation.
Signature	String	Signature for verifying the identity of the callback sender.
EventTime	Number	Unix timestamp (milliseconds) when the event occurred on ZEGOCLOUD servers.
TaskId	String	Digital human video stream task ID.
Detail	Object	Detailed event information. For the structure of this parameter, please refer to Detail.

Detail

The parameters contained in Detail vary depending on the value of EventType.

Callback Examples

Below are callback examples for each EventType.

Signature Verification

To enhance data security, developers should perform local signature calculations when receiving callbacks from the ZEGOCLOUD server, and compare them with the provided signature to determine if the request is legitimate.

The verification process is as follows:

Sort parameters

Sort the three parameters callbacksecret, timestamp, and nonce in dictionary order

Calculate SHA1

Concatenate the sorted callbacksecret, timestamp, and nonce into a string and calculate SHA1

Compare signature

Compare the calculated hash string with signature, if they match, the request is from ZEGOCLOUD

The parameters are described as follows:

Parameter	Description
callbacksecret	Server verification key. Generated when registering a project in the ZEGOCLOUD Console. You can view it in "Console > Project Configuration > Project Information > Configuration Information".
timestamp	Unix timestamp.
nonce	Random number.

Usage Example

The following sample code is used to generate and verify signatures.

PHP Example

// Get signature, timestamp, nonce from request parameters
$signature = $_POST["signature"];
$timestamp = $_POST["timestamp"];
$nonce = $_POST["nonce"];

$secret = callbacksecret;// Get callbacksecret from console
$tmpArr = array($secret, $timestamp, $nonce);
sort($tmpArr, SORT_STRING);
$tmpStr = implode( $tmpArr );
$tmpStr = sha1( $tmpStr );

if( $tmpStr == $signature ){
    return true;
} else {
    return false;
}

// Get signature, timestamp, nonce from request parameters
$signature = $_POST["signature"];
$timestamp = $_POST["timestamp"];
$nonce = $_POST["nonce"];

$secret = callbacksecret;// Get callbacksecret from console
$tmpArr = array($secret, $timestamp, $nonce);
sort($tmpArr, SORT_STRING);
$tmpStr = implode( $tmpArr );
$tmpStr = sha1( $tmpStr );

if( $tmpStr == $signature ){
    return true;
} else {
    return false;
}

Output example:

PHP Example

$nonce = 123412;
$timestamp = 1470820198;
$secret = 'secret';
// The order of the three parameters after sorting is: nonce, timestamp, secret
// The original string to be encrypted after sorting and concatenation is: 1234121470820198secret
// The result of the hash calculation is: 5bd59fd62953a8059fb7eaba95720f66d19e4517

PHP Example

$nonce = 123412;
$timestamp = 1470820198;
$secret = 'secret';
// The order of the three parameters after sorting is: nonce, timestamp, secret
// The original string to be encrypted after sorting and concatenation is: 1234121470820198secret
// The result of the hash calculation is: 5bd59fd62953a8059fb7eaba95720f66d19e4517

Return Response

After you receive the callback, please return an HTTP status code of 2XX (e.g., 200) to indicate successful receipt. Any other response will be considered a failure.

Callback Retry Policy

If the ZEGOCLOUD server does not receive a response, or if the received HTTP status code is not 2XX (e.g., 200), it will attempt to retry, with a maximum of 5 retries. The interval between each retry request and the previous request will be 2s, 4s, 8s, 16s, and 32s respectively. If the 5th retry still fails, no further retries will be attempted, and the callback will be lost.