Help Center/ Live/ Best Practices/ Cloud Live Offers Event Callbacks for Real-Time Event Monitoring

Updated on 2026-03-27 GMT+08:00

View PDF

Cloud Live Offers Event Callbacks for Real-Time Event Monitoring

Live provides callbacks for stream pushing, recording, and snapshot capturing. If callbacks have been configured before livestreaming, when an event is triggered, Live sends an HTTP POST request to your server with the real-time event status included.

Callback Protocols

Request: HTTP POST. The request body is in JSON format.
Response: HTTP STATUS CODE = 200. The response body is in JSON format. You can customize the response body based on your needs.
Example:
```
{ 
  "status": 1, 
  "result" : "success" 
}
```

Overall Process

Figure 1 Callback process

Streaming Callbacks

Streaming callbacks allow you to know whether stream push has started or ended. Table 1 describes the fields in a callback message.

**Table 1** Message body
Field	Description
domain	Ingest domain name
app	Application name
stream	Stream name
user_args	Stream push parameter
client_ip	IP address of the stream push device
node_ip	IP address of the receiver
publish_timestamp	Unix timestamp. One single timestamp is generated for each stream push event.
event	Stream push or stream disconnection Options: PUBLISH: Stream push starts. PUBLISH_DONE: Stream push ends.
auth_timestamp	UNIX timestamp when the event notification signature expires. This parameter is carried when an authentication key is configured. The value is a decimal Unix timestamp, that is, the number of seconds that have elapsed since January 1, 1970 00:00:00 UTC/GMT. Example: 1592639100 (June 20, 2020 15:45)
auth_sign	Event notification signature. This parameter is carried when an authentication key is configured. auth_sign = HmacSHA256 (event + domain + app + stream + auth_timestamp, key) key indicates the key used for authentication.

An example message:

{
    "domain":"push.example.com",
    "app":"live",
    "stream":"example_stream",
    "user_args":"auth_info=yz1TG0PVN/5isfyrGrRj10gKPCWqSS2X02t6QsRrocH+mEq0gQ0g8k6KhalS84sQ+kDprFyqI0yajbYiFmUO8e45B7ryaS+MpJBlYkhwnuFLnRiKK/IXG7.33436b625354564f6e4d4d434f55&cdn=hw",
    "client_ip":"100.111.*.*",
    "node_ip":"112.11.*.*",
    "publish_timestamp":"1587954134,",
    "event":"PUBLISH"
    "auth_timestamp":1587954140,
    "auth_sign":"ff3b2bxxx5cfd56e76d72bed4c4aa2dxxxca8c2e46467d205a6417d4fc"
}

Recording Callbacks

Recording callbacks are available for recording to OBS. You can get notified when recording starts, recording file creation starts, a recording file has been created, recording ends, and recording fails. Table 2 describes the fields in a callback message.

**Table 2** Message body
Field	Description
project_id	Project ID
job_id	Name of a file. This parameter is carried when the value of event_type is RECORD_NEW_FILE_START or RECORD_FILE_COMPLETE.
task_id	Recording task ID, which uniquely identifies a recording task.
event_type	Message type. Possible values are: RECORD_START: This event is triggered when you start recording. RECORD_NEW_FILE_START: This event is triggered in either of the following scenarios: The system starts creating the first recording file. After a live stream is resumed, if Maximum Stream Pause Length is set to Generate a new file after a stream is paused., the system starts creating a recording file. If the recording duration exceeds the configured recording length, the system starts creating a recording file. RECORD_FILE_COMPLETE: This event is triggered in either of the following scenarios: When the recording duration reaches the configured recording length, a recording file has been created. After a live stream is interrupted, if Maximum Stream Pause Length is set to Generate a new file after a stream is paused., a recording file has been created. RECORD_OVER: This event is triggered when a live stream has been paused beyond the time indicated by Maximum Stream Pause Length. RECORD_FAILED: This event is triggered when stream pull fails or recordings fails to be uploaded to OBS.
publish_domain	Ingest domain name
app	App name
stream	Stream name
record_format	Recording format. The HLS, FLV, and MP4 formats are supported.
download_url	Address to download the recording. This parameter is used only when event_type is RECORD_FILE_COMPLETE. NOTE: The quality of video playback using the download address cannot be guaranteed.
asset_id	ID of a recording file. This parameter is used only when event_type is RECORD_FILE_COMPLETE.
file_size	File size Unit: byte
record_duration	Duration of a recording Unit: second
start_time	Start time of a recording, which is, time when the first frame is received. The format is yyyy-mm-ddThh:mm:ssZ. This parameter is used only when event_type is RECORD_FILE_COMPLETE.
end_time	End time of a recording. The format is yyyy-mm-ddThh:mm:ssZ. This parameter is used only when event_type is RECORD_FILE_COMPLETE.
width	Width of a video recording. This parameter is used only when event_type is RECORD_FILE_COMPLETE.
height	Height of a video recording. This parameter is used only when event_type is RECORD_FILE_COMPLETE.
obs_location	Region where the OBS bucket for storing the recording is located. This parameter is used only when event_type is RECORD_FILE_COMPLETE.
obs_bucket	OBS bucket where recordings are stored. This parameter is used only when event_type is RECORD_FILE_COMPLETE.
obs_object	OBS storage path. This parameter is used only when event_type is RECORD_FILE_COMPLETE.
auth_sign	Event notification signature. This parameter is carried when an authentication key is configured. MD5: auth_sign = MD5(key + auth_timestamp) HMACSHA256: HMACSHA256(auth_timestamp + event_type + publish_domain + app + stream + download_url + play_url, key) key indicates the key used for authentication.
auth_timestamp	UNIX timestamp when the event notification signature expires. This parameter is carried when an authentication key is configured. The value is a decimal Unix timestamp, that is, the number of seconds that have elapsed since January 1, 1970 00:00:00 UTC/GMT. If the time specified by auth_timestamp has expired, the notification will become invalid to avoid network replay attacks.
error_message	Description about a failed recording. This parameter is used only when event_type is RECORD_FAILED.

An example message:

If event_type is RECORD_START:

{
  "project_id" : "70b76xxxxxx34253880af501cdxxxxxx",
  "publish_domain" : "push.example.com",
  "event_type" : "RECORD_START",
  "app" : "live",
  "stream" : "mystream",
  "record_format" : "HLS",
  "file_size" : 3957964,
  "record_duration" : 120
}

If event_type is RECORD_NEW_FILE_START,
that is:
- The system starts creating the first recording file.
- After a live stream is resumed, if Maximum Stream Pause Length is set to Generate a new file after a stream is paused., the system starts creating a recording file.
- If the recording duration exceeds the configured recording length, the system starts creating a recording file.
```
{
  "project_id" : "70b76xxxxxx34253880af501cdxxxxxx",
  "publish_domain" : "push.example.com",
  "event_type" : "RECORD_NEW_FILE_START",
  "app" : "live",
  "stream" : "mystream",
  "record_format" : "HLS",
  "file_size" : 3957964,
  "record_duration" : 120
}
```

If event_type is RECORD_FILE_COMPLETE,

that is:

When the recording duration reaches the configured recording length, a recording file has been created.
After a live stream is interrupted, if Maximum Stream Pause Length is set to Generate a new file after a stream is paused., a recording file has been created.

{
  "project_id" : "70b76xxxxxx34253880af501cdxxxxxx",
  "publish_domain" : "push.example.com",
  "event_type" : "RECORD_FILE_COMPLETE",
  "app" : "live",
  "stream" : "mystream",
  "record_format" : "HLS",
  "download_url" : "https://obs.cn-north-4.myhuaweicloud.com/live/record-xxxx-mystream-1589967495/record-push.example.com-live-mystream-1589967495.m3u8",
  "asset_id" : "1a0d8e9bfae388ccbbe5021e62aa1e96",
  "file_size" : 3957964,
  "record_duration" : 120,
  "start_time" : "2020-03-08T14:10:25Z",
  "end_time" : "2020-03-08T14:12:25Z",
  "width" : 1280,
  "height" : 720,
  "obs_location" : "https://obs.cn-north-4.myhuaweicloud.com",
  "obs_bucket" : "mybucket",
  "obs_object" : "live/record-xxxx-mystream-1589967495/record-hwpublish.myun.tv-live-mystream-1589967495.m3u8"
  "auth_sign" : "4f97f46759axxxxxx7ad21e9935dc175",
  "auth_timestamp" : 1583676745
}

download_url indicates the address for downloading the recording file, that is, the address for storing the recording file in the OBS bucket.
asset_id: media asset ID

If event_type is RECORD_OVER, that is, a live stream has been paused beyond the time indicated by Maximum Stream Pause Length and a recording has been created.

{
  "project_id" : "70b76xxxxxx34253880af501cdxxxxxx",
  "publish_domain" : "push.example.com",
  "event_type" : "RECORD_FILE_COMPLETE",
  "app" : "live",
  "stream" : "mystream",
  "record_format" : "HLS",
  "file_size" : 3957964,
  "record_duration" : 120
 }

If event_type is RECORD_FAILED, that is, recording fails because stream pulling fails or uploading recordings to OBS fails:

{
  "project_id" : "70b76xxxxxx34253880af501cdxxxxxx",
  "publish_domain" : "push.example.com",
  "event_type" : "RECORD_FAILED",
  "app" : "live",
  "stream" : "mystream",
  "record_format" : "HLS",
  "file_size" : 3957964,
  "record_duration" : 120,
  "error_message": "Message example"
}

Snapshot Callbacks

This event is triggered when a snapshot file is created. Table 3 describes the fields in a callback message.

**Table 3** Message body
Field	Description
domain	Ingest domain name
app	Application name
stream_name	Stream name
snapshot_url	URL to download snapshots
width	Image width Unit: pixel
height	Image height Unit: pixel
obs_addr	Address of the OBS bucket where snapshots are stored. bucket: OBS bucket name location: Region where the OBS bucket is located object: OBS object path
auth_timestamp	UNIX timestamp when the event notification signature expires. This parameter is carried when an authentication key is configured. The value is a decimal Unix timestamp, that is, the number of seconds that have elapsed since January 1, 1970 00:00:00 UTC/GMT. Example: 1592639100 (June 20, 2020 15:45)
auth_sign	Event notification signature. This parameter is carried when an authentication key is configured. auth_sign = HmacSHA256(domain + app + stream_name + snapshot_url + width + height + obs_addr.bucket + obs_addr.location + obs_addr.object + auth_timestamp,key) key indicates the key used for authentication.

An example message:

{ 
    "domain": "play.example.com",
    "app": "live",
    "stream_name": "test001",
    "snapshot_url": "https://xxx.obs.cn-north-4.myhuaweicloud.com:443...",
    "width":"720",
    "height":"1280",
    "obs_addr": {
        "bucket": "xxx",
        "location": "cn-north-4",
        "object": "xxx.jpg"
    },
    "auth_timestamp":1587954140,
    "auth_sign":"4918b1axxxxxxb583cffa119d72513bbc35a989f8569fxxxxxx057646154a04a"
}

Configuring a Callback URL

Log in to the Live console.
In the navigation pane, choose Domains.
Click Manage in the row containing the target ingest domain name.
Configure a callback URL. The callback URL is the address of your server receiving notification messages, for example, http://test.example.com/notify.

The following three types of callbacks can be configured:

Streaming callbacks: Click the Stream Status Notification tab, click Add, and configure a callback URL for receiving notifications about stream push changes, as shown in Figure 2.

Figure 2 Adding a notification URL

Recording callbacks: Click the Recording (New) tab, click Create Callback Configuration, and configure a callback URL for receiving recording notifications, as shown in Figure 3.
Figure 3 Adding a callback URL

Snapshot callbacks: Click the Snapshot Capturing tab, click Create Snapshot Template, and configure a callback URL for receiving snapshot notifications, as shown in Figure 4.

Figure 4 Creating a snapshot template