Receiving Callbacks

2026-03-31

Warning

Callback services cannot guarantee complete reliability. Please carefully consider the risks of using callbacks to build core business workflows.

Through this callback, you can monitor Digital Human video stream task related information, 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 business backend for receiving callbacks and contact ZEGOCLOUD Technical Support to configure it.
Transport protocol: HTTPS/HTTP. HTTPS is recommended.

Callback Parameters

Note

ZEGOCLOUD will continuously optimize and update callback-related parameters in future iterations (e.g., adding new fields or new parameter values for certain fields). When integrating, please avoid hardcoding to ensure compatibility with new versions after updates.

Parameter	Type	Description
AppId	Number	The unique identifier assigned by ZEGOCLOUD to the developer's app.
EventType	Number	Event notification type. 3: Digital Human video stream task status. 4: Digital Human video stream drive task 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 string, used to verify the callback sender's identity.
EventTime	Number	Unix timestamp (milliseconds) when the event occurred on the ZEGOCLOUD server.
TaskId	String	Digital Human video stream task ID.
Detail	Object	Detailed event information. For the structure of this parameter, refer to Detail.

Detail

Depending on the EventType value, Detail contains different parameters.

Speaking Status Description

If your business needs to sense the digital human speaking status on the server side, you can directly listen to the EventType = 4 drive task callback and map the status as follows:

Detail.Status = 2: The digital human starts speaking.
Detail.Status = 4: The digital human finishes speaking.

This approach is suitable for centrally aggregating status on the server side, and then forwarding it to the client via WebSocket, IM, or custom signaling.

Callback Examples

The following shows callback examples for various events.

If you need to differentiate display based on speaking status, refer to the following examples:

Verify Signature

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.

📕 Example Code

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 receiving a callback, please return an HTTP status code of 2XX (e.g., 200) to indicate successful receipt. Any other response indicates failure.

Callback Retry Policy

If the ZEGOCLOUD server does not receive a response, or the received HTTP status code is not 2XX (e.g., 200), it will retry, up to 5 retries. The intervals between each retry request and the previous request are 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.