Configures stream ingest callbacks for an ingest domain.

Usage note

This interface supports the configuration of the callback address and authentication information of the ingest domain name.

QPS limit

A single user can perform a maximum of 15 queries per second (QPS). Throttling is triggered when the number of calls per second exceeds the QPS limit. The throttling may affect your business. Thus, we recommend that you observe the QPS limit on this operation. For more information about what a single user means and the QPS details, see QPS limit on an API operation in ApsaraVideo Live.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter Type Required Example Description
Action String Yes SetLiveStreamsNotifyUrlConfig

The operation that you want to perform. Set the value to SetLiveStreamsNotifyUrlConfig.

DomainName String Yes demo.aliyundoc.com

The ingest domain.

NotifyUrl String Yes http://guide.aliyundoc.com/notify

The URL to which the callback notifications about stream ingest are sent.

NotifyReqAuth String No yes

Specifies whether to enable authentication. Valid values:

  • yes
  • no

Default value: no.

NotifyAuthKey String No 123***

The cryptographic key. This parameter is required if the NotifyReqAuth parameter is set to yes.

Response parameters

Parameter Type Example Description
RequestId String 40A4F36D-A7CC-473A-88E7-154F92242566

The ID of the request.

Examples

Sample requests

http(s)://live.aliyuncs.com/?Action=SetLiveStreamsNotifyUrlConfig
&DomainName=demo.aliyundoc.com
&NotifyUrl=http://guide.aliyundoc.com/notify
&<Common request parameters>

Sample success responses

XML format 

<SetLiveStreamsNotifyUrlConfigResponse>
      <RequestId>4C747C97-7ECD-4C61-8A92-67AD806331FF</RequestId>
</SetLiveStreamsNotifyUrlConfigResponse>

JSON format 

{
    "RequestId":"4C747C97-7ECD-4C61-8A92-67AD806331FF"
}

Error codes

For a list of error codes, visit the API Error Center.

Callback logic

Callback logic for live stream ingest status:

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. You may require ApsaraVideo Live to send this callback notification only if ApsaraVideo Live receives live streaming data after the connection is established. In this case, submit a ticket.

For example, you have Ingest Domain A and Streaming Domain B, and you use the stream pulling feature for live streaming under Streaming Domain B. You can configure ApsaraVideo Live to pull a stream at the specified point in time, or allow ApsaraVideo Live to automatically pull a stream when the origin server starts live streaming. If you want to receive a callback notification 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.

Note We recommend that you deliver the streaming URL only after you determine that stream ingest or pulling is successful based on callback notifications and the list of online streams.

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.

Special error codes

Error code

Error message

HTTP status code

Description

InternalError

The request processing has failed due to some unknown error.

500

The error message returned because an unknown error occurred.

InvalidDomain.NotFound

The domain provided does not exist in our records.

404

The error message returned because the domain name does not belong to your Alibaba Cloud account.

IllegalOperation

Illegal domain operate is not permitted.

403

The error message returned because the current operation is not supported. For example, the specified domain name is not a live domain.

InvalidNotifyUrl.Malformed

Specified parameter NotifyUrl is not valid.

400

The error message returned because the callback URL is not a valid HTTP URL.

InvalidNotifyUrl.Unsafe

Specified NotifyUrl is not safe.

400

The error message returned because the URL used to receive notifications is unsafe.