ApsaraVideo Live provides callbacks for stream ingest status, live stream recording, live stream snapshots, and automated review. This topic describes how to configure these callbacks in the ApsaraVideo Live console.

Overview

When an event is triggered during live streaming, Alibaba Cloud sends a request to your server and your server then responds to the request. After the verification is passed, a callback message that contains JSON-formatted data is returned to you.

ApsaraVideo Live supports callbacks for events such as stream ingest status, live stream recording (on-demand recording), live stream snapshots, and automated review (video moderation and audio moderation). For information about the callback parameters and examples for different callback events, see Manage callbacks.

Callback methods

ApsaraVideo Live supports event notifications by using HTTP and HTTPS callbacks. You must deploy an HTTP service to receive callback messages and specify a callback URL in the ApsaraVideo Live console or by calling an API operation.

  • When stream ingest is initiated or interrupted, ApsaraVideo Live sends an HTTP GET request to the specified callback URL. The specific event content is included in the URL parameters.
  • When other events are triggered, ApsaraVideo Live sends an HTTP POST request to the specified callback URL. The specific event content is included in the JSON-formatted request body.

Usage notes

  • A callback URL requires no identifier but must be accessible. If no response is returned from the URL within a specific timeout period, ApsaraVideo Live performs retries to access the URL. The current timeout period is 5 seconds. If no response is returned within 5 seconds, ApsaraVideo Live performs retries to access the URL for a maximum of five times at an interval of 1 second.
  • You can configure and modify stream ingest callbacks for only ingest domains. You can configure and modify recording-in-OSS callbacks, snapshot callbacks, video moderation callbacks, and audio moderation callbacks for only streaming domains.

Procedure

  1. Log on to the ApsaraVideo Live console.
  2. In the left-side navigation pane, click Domains to go to the Domain Management page.
  3. Find the ingest domain that you want to configure and click Domain Settings.
    000
  4. Choose Streaming Management > Callbacks. You can configure stream ingest callbacks for the ingest domain.

    • Stream ingest callbacks

      Note You can also call the SetLiveStreamsNotifyUrlConfig operation to configure stream ingest callbacks. For more information, see SetLiveStreamsNotifyUrlConfig. For information about the callback methods and parameters, see Callbacks for stream ingest status.
      1. Turn on Stream Ingest Callbacks.
      2. Configure callback parameters.
        ParameterDescription
        Callback URLThe callback URL is a URL of your own. When a stream is ingested or interrupted, ApsaraVideo Live sends an HTTP GET request to this URL. The specific content is delivered by using URL parameters.
        Callback AuthenticationSpecifies whether to enable authentication for the callback URL. To enable authentication, turn on the switch and specify Authentication Key.
      3. Click OK.

    • Recording-in-OSS callbacks

      If the domain name is an ingest domain, you cannot configure recording-in-OSS callbacks. Recording-in-OSS callbacks are valid for only streaming domains. For more information, see Recording-in-OSS callbacks.

    • Snapshot callbacks

      If the domain name is an ingest domain, you cannot configure snapshot callbacks. Snapshot callbacks are valid for only streaming domains. For more information, see Snapshot callbacks.

    • Video moderation callbacks

      If the domain name is an ingest domain, you cannot configure video moderation callbacks. Video moderation callbacks are valid for only streaming domains. For more information, see Video moderation callbacks.

    • Audio moderation callbacks

      If the domain name is an ingest domain, you cannot configure audio moderation callbacks. Audio moderation callbacks are valid for only streaming domains. For more information, see Audio moderation callbacks.

Stream Ingest callback logic

Callback logic for stream ingest status:
  1. During stream ingest over Real-Time Messaging Protocol (RTMP), ApsaraVideo Live checks whether the stream ingest client closes the connection within 2 seconds after ApsaraVideo Live receives an OnPublish message. If the stream ingest client does not close the connection, ApsaraVideo Live sends a callback notification about the successful stream ingest.
  2. For example, you have Ingest Domain A and Streaming Domain B. You can configure regular stream pulling and triggered stream pulling for Streaming Domain B. If you want to receive callback notifications about the stream pulling status, configure stream ingest callbacks for Ingest Domain A. After the configuration, ApsaraVideo Live uses the same callback logic as that for stream ingest status to send callback notifications about the stream pulling status under Streaming Domain B. By default, ApsaraVideo Live sends a callback notification about successful stream pulling if the stream pulling client does not close the connection within 2 seconds after the connection is established. In this case, live streaming data is received.
Note We recommend that you deliver the streaming URL only after you determine that the stream ingest or pulling is successful based on callback notifications and the list of active streams.

Callback authentication

By default, authentication for stream ingest callbacks is disabled. You can enable the feature when you specify the stream ingest callback URL. After you enable the feature, the following authentication logic applies:
  1. When ApsaraVideo Live initiates a callback request, the ALI-LIVE-TIMESTAMP and ALI-LIVE-SIGNATURE fields are included in the HTTP(S) request header. The callback message receiving server authenticates and signs the fields. The value of ALI-LIVE-SIGNATURE is calculated based on the following formula:

    ALI-LIVE-SIGNATURE = MD5SUM (MD5CONTENT) MD5CONTENT = Domain name|ALI-LIVE-TIMESTAMP value|Authentication key

    Note Domain name is the ingest domain for which you configure the callback URL. Authentication key is the authentication key that you specify for the callback URL.
  2. When receiving a callback message, the callback message receiving server concatenates the domain name, ALI-LIVE-TIMESTAMP value, and authentication key to calculate the MD5 value to obtain an encrypted string. Then, the server compares the encrypted string with the value of the ALI-LIVE-SIGNATURE field in the ApsaraVideo Live HTTP(S) request header. If they are not the same, the request is invalid.