ApsaraVideo Live provides event callbacks for stream ingest status, live recording, live snapshots, and automated review. This topic describes how to configure these callback events in the ApsaraVideo Live console.
Prerequisites
ApsaraVideo Live supports event notifications through HTTP callbacks, which are also compatible with HTTPS. You must deploy an HTTP service to receive callback messages and configure a webhook address in the console or using an API.
When a stream ingest or interruption event occurs, the ApsaraVideo Live server sends an HTTP GET request to this address. The event details are delivered through URL parameters.
When other events occur, the ApsaraVideo Live server sends an HTTP POST request to this address. The event details are delivered in a JSON body.
Scenarios
When specific events are triggered during a live stream, Alibaba Cloud sends a request to your server. Your server is responsible for acknowledging the request. After successful authentication, you can retrieve the event callback information in a JSON data packet.
ApsaraVideo Live supports callbacks for events such as stream ingest status, live recording (on-demand recording), live snapshot, and automated review (video and audio review). For more information about the callback parameters and examples for different events, see Manage callbacks.
Limits
The webhook address URL does not require authentication. It only needs to be publicly accessible. The URL acknowledgement has the following requirements:
If a request to the URL times out, the request is retried. The timeout period is 5 seconds, the number of retries is 5, and the retry interval is 1 second.
Configuration requirements for different callback types:
Stream ingest callbacks can only be configured and edited for ingest domains.
Recording, snapshot, video review, and audio review callbacks can only be configured and edited for streaming domains.
Function introduction
Event callbacks are categorized into ingest callbacks and streaming callbacks.
Stream ingest callback: You can set the stream ingest callback and callback authentication for an ingest domain.
Streaming callbacks: For a streaming domain, you can configure recording callback, snapshot callback, video moderation callback, and audio moderation callback.
Callback records: You can use callback records to quickly view the records and content of callback events for live recordings that are stored in OSS. For more information, see Callback records.
Operation guide
Log on to the ApsaraVideo Live console.
In the navigation pane on the left, click Feature Management > Callbacks to open the Callbacks page.
Select the ingest or streaming domain that you want to configure. You can configure ingest callbacks for ingest domains. You can configure recording, snapshot, video review, and audio review callbacks for streaming domains.
On the Callback Settings tab, you can configure the features.
Ingest callback
You can enable Stream Ingest Callbacks.
Configure the callback parameters.
Parameter
Description
Callback Type
Ingest/Interruption callback: Notifies you of successful stream ingest and stream interruption for the current domain name.
Anomalous ingest event callback: Notifies you of anomalous stream ingest events for the current domain name.
Callback URL
Ingest/Interruption webhook address: This is a URL that you own. When a stream ingest or interruption event occurs, the ApsaraVideo Live server sends an HTTP GET request to this address. The details are delivered through URL parameters.
Anomalous event webhook address: This is a URL that you own. When an anomalous stream ingest event occurs, the ApsaraVideo Live server sends an HTTP POST request to this address. The details are delivered in a JSON body.
Callback Authentication
Select whether to enable authentication for the ingest callback address. To enable authentication, turn on the switch and enter the Encryption Key.
Click OK.
For more information about the callback method and content, see Live stream ingest callback. You can also call the SetLiveStreamsNotifyUrlConfig API operation.
Recording callback
Enable Recording Callbacks.
Configure the callback parameters.
Parameter
Description
Callback Type
This is a URL that you own. When a recording callback event occurs, the ApsaraVideo Live server sends an HTTP POST request to this address. The details are delivered in a JSON body.
Triggering Event
File generation callback: A callback is triggered when a recording file is generated.
Recording status callback: A callback is triggered for events such as recording file generation, recording start, pause, and resume.
On-demand Callback URL
After you configure on-demand recording, when a live stream ingest starts, the live recording service sends an HTTP callback to the pre-configured on-demand webhook address. The response from this callback determines whether to record the live stream. The default value for the on-demand webhook address is
*, which means on-demand recording is disabled.NoteBefore setting the on-demand webhook address, you must call the AddLiveAppRecordConfig API operation to configure recording rules. Set the
OnDemandparameter to1to enable on-demand recording through HTTP callbacks.Callback Authentication
This feature is disabled by default. If you enable it, you must set the Authentication Key. The system signs each callback request, and the recipient can perform signature verification to ensure the request is secure. For more information about the procedure, see Callback authentication.
Click OK.
For more information about the callback method and content, see Live recording callback. You can also call the AddLiveRecordNotifyConfig API operation.
Snapshot callback
Enable Snapshot Callbacks.
Configure the callback parameters.
Parameter
Description
Callback URL
This is a URL that you own. When a snapshot callback event occurs, the ApsaraVideo Live server sends an HTTP POST request to this address. The details are delivered in a JSON body.
Callback Authentication
Select whether to enable authentication for the snapshot callback address. To enable authentication, turn on the switch and enter the Encryption Key.
For more information about the callback method and content, see Live snapshot callback. You can also call the AddLiveSnapshotNotifyConfig API operation.
Video review callback
You can enable Video Moderation Callbacks.
Configure the webhook address.
This is a URL that you own. When a video review callback event occurs, the ApsaraVideo Live server sends an HTTP POST request to this address. The event details are delivered in a JSON body.
Click OK.
For more information about the callback method and content, see Automated review callback. You can also call the AddLiveDetectNotifyConfig API operation to add a callback notification URL.
Automated review for live streams is supported only in specific live centers. For more information about the live centers that support this feature, see Supported regions.
Video review callbacks are triggered only for problematic video content. The notification contains the review and storage information of the snapshot of the problematic video. You can view the callback information on your callback server. For more information about the format of and examples for the callback information, see Automated review callback.
Find the detected content in OSS. You can find the specified reviewed content in the OSS console based on the information from the review callback.
Find the specified reviewed content by AppName and StreamName.
Find the specified reviewed content by ingest date.
Audio review callback
You can enable Audio Moderation Callbacks.
Configure the webhook address.
This is a URL that you own. When an audio review callback event occurs, the ApsaraVideo Live server sends an HTTP POST request to this address. The event details are delivered in a JSON body.
Click OK.
For more information about the callback method and content, see Automated review callback. You can also call the AddLiveAudioAuditNotifyConfig API operation to add audio review callback information.
Audio review callbacks are triggered only for problematic audio content. The notification contains the text of the problematic audio and contextual information from the preceding minute. You can view the callback information on your callback server. For more information about the format of and examples for the callback information, see Automated review callback.
Find the detected content in OSS. You can find the specified reviewed content in the OSS console based on the information from the review callback.
Find the specified reviewed content by AppName and StreamName.
Find the specified reviewed content by ingest date.
Ingest callback logic
The logic for the publish status callback in the ingest status callback is as follows:
For RTMP stream ingest, if the ingest client does not actively disconnect within 2 seconds after the ApsaraVideo Live service receives an On Publish message, the service sends a successful ingest callback.
Assume you have an ingest domain A and a streaming domain B. If you require callbacks for stream pulling on domain B (either fixed or triggered back-to-origin stream pulling), you must configure an ingest callback for domain A. After the configuration is complete, the stream pulling callback logic for domain B is the same as described in the preceding step. A successful stream pulling is assumed if the connection is not actively disconnected within 2 seconds after it is established.
You can use callback notifications to determine whether stream ingest and stream pulling are normal. You can also query the list of active streams to confirm that the stream ingest is normal before you distribute the playback URL of the live stream.
Callback authentication
The callback authentication feature for stream ingest is disabled by default. You can enable authentication when you configure the ingest callback address. After you enable this feature, the authentication logic is as follows:
When ApsaraVideo Live initiates a callback request, it includes the
ALI-LIVE-TIMESTAMPandALI-LIVE-SIGNATUREfields in the HTTP or HTTPS request header. This allows the server that receives the callback message to perform signature authentication. The value ofALI-LIVE-SIGNATUREis calculated as follows:ALI-LIVE-SIGNATURE=MD5SUM(MD5CONTENT) where MD5CONTENT= CallbackDomain | Value of ALI-LIVE-TIMESTAMP | EncryptionKEY.
NoteThe callback domain is the ingest domain for which the callback URL is configured. The encryption key is the key that you configure for the ingest callback URL.
When your server receives a callback message, it concatenates the callback domain, the value of
ALI-LIVE-TIMESTAMP, and the encryption key. Your server then calculates the MD5 hash of the concatenated string to obtain an encrypted string. The server then compares the calculated encrypted string with the value of theALI-LIVE-SIGNATUREfield in the HTTP or HTTPS request header sent by ApsaraVideo Live. If the strings do not match, the request is considered invalid.