Configures stream ingest callbacks for an ingest domain.

Usage notes

You can call this operation to configure the callback URL and authentication information of an ingest domain.

QPS limit

You can call this operation up to 15 times per second per account. Requests that exceed this limit are dropped and you will experience service interruptions. We recommend that you take note of this limit when you call this operation. For more information, 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 stream ingest callbacks are sent.

NotifyReqAuth String No yes

Specifies whether to enable callback authentication. Valid values:

  • yes: enables callback authentication. If you set this parameter to yes, you must also specify the NotifyAuthKey parameter.
  • no: disables callback authentication.
Note Default value: no.

For information about the authentication logic, see Authentication for stream ingest callbacks.

NotifyAuthKey String No 123456

The authentication key.

Note This parameter is required if you set the NotifyReqAuth parameter to yes.

Value requirements:

  • The key must be 16 to 64 characters in length.
  • The key can contain letters and digits.

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

HTTP/1.1 200 OK
Content-Type:application/xml

<?xml version="1.0" encoding="UTF-8" ?>
<SetLiveStreamsNotifyUrlConfigResponse>
	<RequestId>4C747C97-7ECD-4C61-8A92-67AD806331FF</RequestId>
</SetLiveStreamsNotifyUrlConfigResponse>

JSON format

HTTP/1.1 200 OK
Content-Type:application/json

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

Error codes

HttpCode Error code Error message Description
400 ConfigAlreadyExists Config has already exist. The error message returned because the configuration already exists.

For a list of error codes, see Service error codes.

Callback logic

Callback logic for 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. If your business requires ApsaraVideo Live to send this callback notification only when ApsaraVideo Live receives live streaming data after the connection is established, submit a ticket. For more information about how to submit a ticket, see Contact us.

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.

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 active streams.

Authentication for stream ingest callbacks

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, it includes the ALI-LIVE-TIMESTAMP and ALI-LIVE-SIGNATURE headers in the HTTP or HTTPS request so that the callback message receiving server can authenticate the signature. The value of ALI-LIVE-SIGNATURE is calculated based on the following formula:

ALI-LIVE-SIGNATURE = MD5SUM (MD5CONTENT) MD5CONTENT = <Domain name of the callback>|<ALI-LIVE-TIMESTAMP value>|<Authentication key>

2. After receiving a callback message, the callback message receiving server concatenates the domain name of the callback, value of the ALI-LIVE-TIMESTAMP header, and authentication key in the preceding format. The server calculates the MD5 value of the string to obtain an encrypted string. Then, the server compares the encrypted string with the value of the ALI-LIVE-SIGNATURE header in the HTTP or HTTPS request initiated by ApsaraVideo Live. If the two values are different, the request is 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 is not found under 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 domain name in ApsaraVideo Live.

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 callback URL is unsecure.