Event Callback

Updated on 2024-09-27 GMT+08:00

View PDF

Live provides callback for stream pushing, recording, and snapshot capturing. If callback has been configured before livestreaming, when an event is triggered, Live sends an HTTP POST request to your server with 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 Callback

Streaming callback allows 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 pushing parameter
client_ip	IP address of the streaming device
node_ip	IP address of the receiver
publish_timestamp	Unix timestamp. One single timestamp is generated for each stream pushing event.
event	Stream pushing or stream disconnection. Options: PUBLISH: Stream pushing starts. PUBLISH_DONE: Stream pushing 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 (midnight 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 Callback

Recording callback is available for recording to OBS. You will be notified when recording starts, a recording file starts creating, 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_FILE_COMPLETE, 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 Callback

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 (midnight 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 the Callback URL

Log in to the Live console.
In the navigation pane, choose Domains.
Click Management in the row containing the target ingest domain name.
Configure the callback URL.

The callback URL is the address of your server receiving notification messages, for example, http://test.example.com/notify.
- Streaming callback
  In the navigation pane, choose Template > Stream Status Notifications, and click Add to add a notification URL.
  
  Figure 2 Adding a streaming callback
- Recording callback
  In the navigation pane, choose Template > Recording (New Version) and click Create Callback Configuration to configure a recording callback URL.
  Figure 3 Adding a recording callback
- Snapshot callback
  In the navigation pane, choose Template > Snapshot. Click Create Snapshot Template. On the displayed page, toggle on Callback and add a callback URL.
  
  Figure 4 Adding a snapshot callback