Receiving Callbacks

2026-03-16

Note

Callback service cannot be guaranteed to be completely reliable. Please carefully consider the risks of using callback solutions to build core business processes.

Through this callback, you can monitor events that occur during real-time speech recognition, including ASR results and exception events.

Note

Please ensure that you have successfully started the real-time speech recognition task by referring to the Start Task interface.

Callback Description

Request method: POST.
Note
The callback data format is JSON. You need to perform UrlDecode decoding on it.
Request address: Please provide the address for your business server to receive callbacks and contact ZEGOCLOUD Technical Support to configure it.
Transport protocol: HTTPS/HTTP, HTTPS is recommended.

Callback Parameters

Note

ZEGO will continue to optimize and update the relevant callback parameters in future iteration plans (for example: adding new fields or new parameter values for certain fields). When integrating, developers should avoid hard-coding to ensure compatibility with new versions after updates.

Parameter	Type	Description
AppId	Number	The unique identifier of the developer's APP assigned by ZEGO.
Event	String	Event notification type. ASRResult: ASR result. TranslationResult: Translation result. Exception: Exception event.
Nonce	String	Random number, used for signature string calculation.
Timestamp	Number	Unix timestamp (milliseconds) when the callback is sent, used for signature string calculation.
Signature	String	Signature string, used to verify the identity of the callback sender.
TaskId	String	The unique identifier of the task, globally unique.
RoomId	String	Room ID.
Data	Object	Event details. Depending on the Event value, the members of this callback parameter are different.

Data

Depending on the Event value, the parameters included in Data are different.

Callback Example

The following shows callback examples for each Event.

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

When you receive a callback, please return HTTP status code 2XX (for example, 200) to indicate successful reception. Returning anything else indicates reception failure.

Callback Retry Policy

If the ZEGO server does not receive a response, or receives an HTTP status code other than 2XX (for example, 200), it will attempt to retry, up to 5 retries. The interval between each retry request and the previous request is 2s, 4s, 8s, 16s, 32s respectively. If it still fails after the 5th retry, no more retries will be made, and the callback will be lost.