If you configure callbacks for the real-time stream status, you can receive callback notifications about successful or interrupted stream ingests.

How it works

ApsaraVideo Live sends an HTTP GET request to your server to notify you of the successful stream ingest or stream interruption in real time. The server then responds with the HTTP status code 200, which indicates that the callback is successful.

Usage notes

  • A callback URL requires no identifier but must be accessible. The URL response complies with the following requirements:

    If no response is returned from the URL in a specific period, ApsaraVideo Live retries to access the URL. If no response is returned in 5 seconds, ApsaraVideo Live retries to access the URL for a maximum of five times at intervals of 1 second.

  • Callback logic
    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.
    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 is complete, the preceding callback logic is used for Streaming Domain B. By default, stream pulling is considered successful if the connection is established for 2 seconds.
    Note We recommend that you release the streaming URL after you confirm that the stream ingest or pulling is successful based on callback notifications and the results of the DescribeLiveStreamsOnlineList operation.
  • Callback authentication logic
    The callback authentication is disabled by default. You can enable it while configuring the callback URL. The authentication logic is as follows:
    1. ApsaraVideo Live includes the ALI-LIVE-TIMESTAMP and ALI-LIVE-SIGNATURE fields in the HTTP(S) request header when sending callback information to the callback URL. The value of ALI-LIVE-SIGNATURE is calculated using the following formula:

      ALI-LIVE-SIGNATURE=MD5SUM (MD5CONTENT)

      MD5CONTENT=Stream pushing domain name|Value of ALI-LIVE-TIMESTAMP|Cryptographic key
      Note The Stream pushing domain name refers to the domain to which the callback URL is configured. The Cryptographic key refers to the authentication key for the callback URL.
    2. The server that hosts the callback URL generates an MD5 hash from a concatenated string of the stream pushing domain name, the value of ALI-LIVE-TIMESTAMP, and the cryptographic key. It then compares the MD5 hash with the value of ALI-LIVE-SIGNATURE in the HTTP(S) request header. If the MD5 hash is not consistent with the value of ALI-LIVE-SIGNATURE, the request is considered invalid.

Examples

The following table describes the parameters in the sample callback URL:
http://1.1.1.1?action=publish&ip=192.168.XX.XX&id=world&app=example.aliyundoc.com&appname=liveApp****&time=1609220385&usrargs={Custom parameters}&
node=cdnvideocenter01020711****.cm3&height=720&width=1280
.
ParameterDescription
actionThe name of the event. Valid values:
  • publish: stream ingest
  • publish_done: stream interruption
ipThe IP address of the stream ingest client.
idThe name of the ingested stream.
appThe ingest domain. The default value is a custom ingest domain. If no ingest domain is bound, a streaming domain is used.
appnameThe name of the application that ingests the stream.
timeUNIX timestamp. Unit: seconds.
usrargsThe custom parameters that are used to ingest the stream.
nodeThe name of the Alibaba Cloud CDN node or the host that receives the stream.
heightThe height of the resolution. Unit: pixel.
Note The height and width of the resolution are returned only when the callback is invoked for the first time.
widthThe width of the resolution. Unit: pixel.