Callback Configuration Description

2026-03-05

When using ZEGOCLOUD server API, developers can connect to the business backend through Callback services to further ensure the orderly and normal operation of the business.

Warning

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

Usage scenarios

For example:

After the client successfully Publishes a stream, the business backend can receive the Stream created Callback from the ZEGOCLOUD server to add to the live broadcast list (maintainable live broadcast list).

Note

The "pic_url" in the Stream created Callback can be used for moderation. The default is a cached image every 20s.
"pic_url" can only be used during the Publish stream process and becomes invalid after the Publish stream ends.

After the client stops Publishing a stream, the business backend can receive the Stream destroyed Callback from the ZEGOCLOUD server to delete from the live broadcast list (maintainable live broadcast list).
After the client ends the live broadcast, the business backend can receive the Recording file generated Callback from the ZEGOCLOUD server to implement on-demand services.

Callback configuration

Developers can configure Callback information in the ZEGO Console under "Project Configuration > Server Callback Configuration" according to actual business needs.

At the same time, you can configure the URL address to receive ZEGO callbacks as needed.

Note

You can view the console interface as follows:

Users who registered for the ZEGOCLOUD Console after 2021-11-16, please refer to Console - Server Callback Configuration.
Users who registered for the ZEGOCLOUD Console on or before 2021-11-16, please refer to "Advanced Configuration" in Console (Old Version) - Project Management.

Callback description

Request method: POST.

Note

The Callback data format is JSON. You need to perform UrlDecode decoding on it.

Transfer protocol: HTTPS/HTTP. HTTPS is recommended.

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

Return HTTP status code 2XX (e.g., 200) indicates success, and other responses indicate failure.

Callback retry strategy

If the ZEGO server does not receive a response, or the received HTTP status code is not 2XX (e.g., 200), it will attempt to retry, up to 5 retries. The interval between each retry request and the last request is 2s, 4s, 8s, 16s, and 32s respectively. If the 5th retry still fails, no more retries will be made, and the Callback will be lost.