Cloud recording callback notifications

Cloud recording callbacks use HTTP/HTTPS POST requests to notify your server of recording task status changes, including task lifecycle events and file upload completions.

Cloud recording callback retry mechanism

The system resends a callback message if the response error code is 500 or greater, or if a request times out.

Cloud recording callback message format

Callback messages are POST requests sent over HTTP or HTTPS to your configured URL.
The request body is in JSON format.

After you receive a callback message, you must return the following response:

Header

HttpStatus

Body

Content-Type: application/json

200

{

"Code": 0,

"Msg": "Success"

}

Cloud recording callback parameters

Note

Currently, cloud recording callback notifications only support events related to task status changes.

Callback message header

Parameter	Value
Content-Type	application/json
ALI-LIVE-TIMESTAMP	This parameter is passed only when NotifyAuthKey is valid. Example: 1748417138
ALI-LIVE-SIGNATURE	This parameter is passed only when NotifyAuthKey is valid. Example: abcdefgxxx

Authentication instructions: If you provide a valid NotifyAuthKey when you create a cloud recording task, the system includes the ALI-LIVE-TIMESTAMP and ALI-LIVE-SIGNATURE fields in the callback HTTP request header. Use these fields to verify the callback signature and confirm the message is from a trusted source.

The ALI-LIVE-SIGNATURE is generated as follows:

ALI-LIVE-SIGNATURE = MD5(MD5CONTENT)
MD5CONTENT = ALI-LIVE-TIMESTAMP + "|" + NotifyAuthKey

After you receive the callback request, fetch the ALI-LIVE-TIMESTAMP and ALI-LIVE-SIGNATURE from the request header.
Generate the MD5CONTENT string by concatenating your locally stored NotifyAuthKey with the ALI-LIVE-TIMESTAMP value from the request header. Use a pipe character (|) as a separator.
Calculate the MD5 hash of the MD5CONTENT string to obtain the signature.
Compare the calculated signature with the ALI-LIVE-SIGNATURE from the request header.

If the signatures do not match, reject the request because it may be from an untrusted source.

Callback message body

Parameter	Type	Description
appId	string	The application ID.
channelId	string	The channel ID.
taskId	string	The recording task ID.
eventType	string	The event type. For more information, see the Event types table.
callbackTs	integer	The time when the callback was sent, as a UNIX timestamp in milliseconds. Example: 1744774345595.
payload	json string	Other information. For more information about the parameters, see the Other information table.

Event types (eventType)

Value	Description
TaskCreated	The task is created.
TaskStarting	The task is starting.
TaskRunning	The task is running.
TaskRecovering	The task is recovering from an exception.
TaskStopping	The task is stopping.
TaskStopped	The task is stopped.
TaskStartFailed	The task failed to start.
TaskUpdated	The task is updated successfully.
TaskUpdateFailed	The task failed to update.
RecordStart	The recording starts.
RecordFailed	The recording failed to recover from an exception and timed out.
RecordFileUploaded	The recording file is uploaded.

Other information (payload)

Parameter	Type	Description
eventTs	integer	The time when the event occurred, as a UNIX timestamp in milliseconds. Example: 1744774345595.
taskStatus	string	The task status. For more information, see the Task statuses table. Note This parameter is not returned when eventType is RecordFileUploaded.
errorCode	string	The error code. For more information, see the Errors table.
errorMessage	string	The error message. For more information, see the Errors table.
recordFileList	FileList	The list of recording files. For more information about the parameters, see the FileList table. Note This parameter is returned only when eventType is TaskRunning, TaskStopping, or TaskStopped.
recordFile	RecordFile	Recording file details, returned only when eventType is RecordFileUploaded. For more information, see the RecordFile table.
format	string	The recording file format. Returned only when eventType is RecordFileUploaded. Valid values: SLICE (not supported) HLS MP4 MP3
streamInfo	string	Returned only when eventType is RecordStart. Indicates which subscribed stream started recording. For stream mixing recordings, the value is always Mix. For single-stream recordings, the value is Single::{UserId}::{Suffix}. UserId is the ID of the user corresponding to the stream. Suffix depends on the StreamType and SourceType specified during subscription: If StreamType is 0: Suffix is AV::C if SourceType is 0, or AV::S if SourceType is 1. If StreamType is 1: Suffix is always A. If StreamType is 2 (not supported for single-stream recording): Suffix is V::C if SourceType is 0, or V::S if SourceType is 1.

Recording file list (FileList)

Parameter	Type	Description
mp3FileList	array<string>	An array of MP3 recording file names.
mp4FileList	array<string>	An array of MP4 recording file names.
hlsFileList	array<string>	An array of HLS recording file names.
vodMediaList	array<VodFileInfo>	An array of VOD media resources, populated only when recording to VOD. Each item corresponds to a subscribed stream. For more information, see the VodFileInfo table.

VOD file information (VodFileInfo)

Parameter	Type	Description
stream	string	The subscribed stream. For stream mixing recordings, the value is always Mix. For single-stream recordings, the value is Single::{UserId}::{Suffix}. UserId is the ID of the user corresponding to the stream. Suffix depends on the StreamType and SourceType specified during subscription. If StreamType is 0: Suffix is AV::C if SourceType is 0, or AV::S if SourceType is 1. If StreamType is 1: Suffix is always A. If StreamType is 2 (not supported for single-stream recording): Suffix is V::C if SourceType is 0, or V::S if SourceType is 1.
mediaIds	array<string>	An array of media resource IDs generated during the recording.
mergedIds	array<string>	An array of media resource IDs automatically merged after recording ends. Populated only when you record to VOD, enable automatic merging, and produce more than one media resource.

Recording file information (RecordFile)

Parameter	Type	Description
sliceFile	string	Returned only if this format is specified in the NotifyFileUploadedFormat parameter.
hlsFile	string	Returned only if this format is specified in the NotifyFileUploadedFormat parameter.
mp4File	string	Returned only if this format is specified in the NotifyFileUploadedFormat parameter.
mp3File	string	Returned only if this format is specified in the NotifyFileUploadedFormat parameter.

Task statuses (taskStatus)

Note

The task status is not affected by successful or failed updates. Therefore, the `taskStatus` field does not include these statuses.

Status	Description
CREATED	Returned when the task is created.
STARTING	Returned when the task is starting.
RUNNING	Returned when the task is running.
RECOVERING	Returned when the task is recovering from an exception.
STOPPING	Returned when the task is stopping.
STOPPED	Returned after the task is stopped.
FAILED	Returned after the task fails to start.

Errors

Note

These parameters are populated only when `eventType` is `TaskRecovering`, `TaskStartFailed`, or `TaskUpdateFailed`. For all other event types, they are empty.

Event type (eventType)	Error code (errorCode)	Error message (errorMessage)	Description
Task start failed (TaskStartFailed)	StartTaskError	Channel already closed	The channel is closed.
Task start failed (TaskStartFailed)	StartTaskError	Start task error	Other reasons.
Recovery from an abnormal state (TaskRecovering)	RunTaskError	The rms task failed	The stream mixing module is running abnormally.
Recovery from an abnormal state (TaskRecovering)	RunTaskError	The record task failed	The recording module is running abnormally.
The task update failed. (TaskUpdateFailed)	UpdateTaskError	Update task error	The task failed to update.
RecordFailed	RunTaskError	Recovering status timeout	The recovery from an exception timed out.

Callback examples

TaskStopped event:

{
    "appId": "mytestappid",
    "callbackTs": 1755504873034,
    "channelId": "room1047",
    "eventType": "TaskStopped",
    "payload": "{\"eventTs\":1755504873014,\"taskStatus\":\"STOPPED\",\"errorCode\":\"\",\"errorMessage\":\"\",\"streamInfo\":\"\",\"recordFileList\":{\"mp3FileList\":[],\"mp4FileList\":[\"mp4/fe60a6e3-cecb-3fae-a8cf-3d2391f507a5/mytestappid_room1047_2025-08-18-15:59:16.mp4\",\"mp4/fe60a6e3-cecb-3fae-a8cf-3d2391f507a5/mytestappid_room1047_2025-08-18-16:02:16.mp4\"],\"hlsFileList\":[\"hls/fe60a6e3-cecb-3fae-a8cf-3d2391f507a5/mytestappid_room1047_2025-08-18-15:59:16.m3u8\",\"hls/fe60a6e3-cecb-3fae-a8cf-3d2391f507a5/mytestappid_room1047_2025-08-18-16:02:16.m3u8\"],\"vodMediaList\":[]}}",
    "taskId": "fe60a6e3-cecb-3fae-a8cf-3d2391f507a5"
}

RecordFileUploaded event:

{
    "appId":"mytestappid",
    "callbackTs":1764301584289,
    "channelId":"room1406",
    "eventType":"RecordFileUploaded",
    "payload":"{\"eventTs\":1764301584265,\"errorCode\":\"\",\"errorMessage\":\"\",\"streamInfo\":\"Single::userA::AV::C\",\"format\":\"MP4\",\"recordFile\":{\"sliceFile\":\"\",\"hlsFile\":\"\",\"mp3File\":\"\",\"mp4File\":\"mp4/07c2e845-630d-36a1-b2d1-3b546efdea90/mytestappid_room1406_userA_2025-11-28-11:46:03.mp4\"}}",
    "taskId":"07c2e845-630d-36a1-b2d1-3b546efdea90"}