Recording status callback

Warning

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

Description

To receive a task status event immediately upon a status change, you need to provide a callback URL when enabling the Cloud Recording service.

During recording, an HTTP request will be initiated to the callback URL using the POST method and the request message body is in JSON format.

Callback parameters

Parameter	Type	Description
app_id	Int64	Unique AppID assigned by ZEGOCLOUD.
task_id	String	Task ID. The value is a 16-byte character string.
room_id	String	Room ID.
event_type	Int	Event type. 1: The upload status of a recording file changes. For details, see the `detail` parameter. 2: A recording task ends abnormally. For details, see the `detail` parameter. 3: The customized background or watermark image failed to be downloaded. For details, see the `detail` parameter. 4: The number of streams in the room where recording is performed is zero. This event will be triggered within 30 seconds after the number of streams in the room becomes zero. After the first-time event trigger, if the room remains in the no-stream state, this event will be triggered once again every 30 seconds until a stream is detected or the task times out. 5: The recording is completed. 6: The stream to be recorded does not exist. For details, see the `detail` parameter. 7: Uploading recorded file. 102: When uploading video segments in real-time, notify the M3U8 file address. 201: Recording paused successfully. 202: Recording resumed successfully.
message	String	Event description.
nonce	String	Random number, which is used to generate a signature.
timestamp	String	Unix timestamp when a callback is triggered, which is used to generate a signature.
signature	String	Signature used to verify the identity of the callback sender.
sequence	Int	Message sequence number, which starts from 0.
detail	JSON Object	Detailed event information. The member parameters vary depending on the value of `event_type`.

detail

See the details of the fields included in detail based on different values of event_type.

4, 5, 7, 201, or 202

102

Note

ZEGOCLOUD will update parameters (for example, add parameters or values) in the recording status callback method in future iterations. Therefore, avoid performing hard coding upon integration. Otherwise, incompatibility may occur after a version iteration.

Sample

Untitled

{
    "app_id": 1234567890, 
    "detail": {
        "file_info": [
            {
                "begin_timestamp": 1637753762084, 
                "duration": 170039, 
                "file_id": "YZ4joOE4IwmFAAAT_6677_800221_800221_VA_20211124113602084.mp4", 
                "file_size": 25349026, 
                "file_url": "file_url", 
                "media_track_type": 3, 
                "output_file_format": "mp4", 
                "resolution_height": 720, 
                "resolution_width": 1280, 
                "status": 3, 
                "stream_id": "800221", 
                "user_id": "800221", 
                "user_name": "play_800221", 
                "video_id": ""
            }
        ], 
        "upload_status": 1
    }, 
    "event_type": 1, 
    "message": "", 
    "nonce": "100480", 
    "room_id": "6677", 
    "sequence": 1, 
    "signature": "12345678987654321", 
    "task_id": "YZ4joOE4IwmFAAAT", 
    "timestamp": "1637753949"
}

Copied!

Source verification

Checks whether a callback request is initiated from the Cloud Recording service.

Verification method

Check whether the calculated signature is the same as that carried in the callback request. The following figure shows how to calculate a signature.

nonce: parameter in the callback request
timestamp: parameter in the callback request
callbacksecret: generated during project registration on the ZEGOCLOUD Admin Console.

Sample code

Sample code in PHP:

Untitled

$signature = $_POST["signature"];
$timestamp = $_POST["timestamp"];
$nonce = $_POST["nonce"];

$secret = callbacksecret;// Callback secret obtained in the background.
$tmpArr = array($secret, $timestamp, $nonce);
sort($tmpArr, SORT_STRING);
$tmpStr = implode( $tmpArr );
$tmpStr = sha1( $tmpStr );

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

Copied!

Sample code in Java:

Untitled

// Obtain the values of signature, timestamp, and nonce from the request.
String signature = request.getParameter("signature");
long timestamp = request.getParameter("timestamp");
String nonce = request.getParameter("nonce");

// Back end obtains callbacksecret
String secret = callbacksecret;

String[] tempArr = {secret, ""+timestamp, nonce};
Arrays.sort(tempArr);
        
String tmpStr = "";
for (int i = 0; i < tempArr.length; i++) {
    tmpStr += tempArr[i];
}
tmpStr = org.apache.commons.codec.digest.DigestUtils.sha1Hex(tmpStr);

return tmpStr.equals(signature);

Copied!

Sample response

Untitled

$timestamp = 1470820198;
$nonce = 123412;
$secret = 'secret';
	
Original string requiring encryption after ranking splice:1234121470820198secret
The result of encryption will be:5bd59fd62953a8059fb7eaba95720f66d19e4517

Copied!

Return code

HTTP status code 2XX (such as 200) indicates success and all other return codes indicate failure.