ApsaraVideo Live:CreateEventSub

You can call this operation to create a callback to subscribe to channel or user events. When you create a callback, you can configure parameters such as the callback URL and event type.

QPS limit

You can call this operation up to 100 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.

CallBack

Callback messages are sent to the callback URL that is specified by the CallbackUrl parameter. The following sample code provides an example:

Request:

POST /callbackURL

Body
application/json

{
    "MsgId": "Message ID",
    "MsgTimestamp": 12312324, // The UNIX timestamp when the message was sent.
    "SubscribeID": "Subscription ID",
    "AppId":"",     // The ID of the application in which the message was generated.
    "ChannelID":"", // The ID of the channel in which the message was generated.
    "Contents": [
      {
        "Event": "UserEvent",// The type of the event that is subscribed to. In this case, the type is user event.
        "UserEvent": {
          "UserId": "80331631628*****",    // The user ID.
          "EventTag": "Publish",    // The event. Valid values: Join, Leave, Publish, Unpublish, and Roleupdate.
          "SessionId": "0dr15rrnhkz0jnvz6o8sxo0*****", // The ID of the session in which the event was generated.
          "Timestamp": 1609854786,    // The UNIX timestamp when the event occurred.
          "Reason": 1, // The reason for joining or leaving the channel. This parameter is available only if the event is a Join event.
          "Role": 1, // The role of the user. The roles include streamer and viewer.
          "CurrentMedias":"1,2,3"// The types of the streams that were ingested by the user.
        }
      },
      {
        "Event": "ChannelEvent",// The type of the event that is subscribed to. In this case, the type is channel event.
        "ChannelEvent": {
          "ChannelId": "88888****",
          "EventTag": "Open",   // The event. Valid values: Open and Close.
          "Timestamp": 1609854530 // The UNIX timestamp when the event occurred.
        }
      }
   ]
}

Response 
HTTP STATUS 200

Parameters of a user event

Parameters of a channel event

Callback authentication

By default, callback authentication is enabled. The following authentication logic applies:

• When ApsaraVideo Live initiates a callback request, it includes the Ali-Rtc-Timestamp and Ali-Rtc-Signature headers in the HTTP or HTTPS request so that the callback message receiving server can authenticate the signature. The value of Ali-Rtc-Timestamp is calculated based on the following formula: Ali-Rtc-Signature=MD5SUM(MD5CONTENT). In the formula, MD5CONTENT is a string in the following format: Callback domain name|Ali-Rtc-Timestamp value|Authentication key. The callback domain name is the domain name in the callback URL. The authentication key is the AppKey of the application.

• After receiving a callback message, the callback message receiving server concatenates the callback domain name, value of the Ali-Rtc-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-Rtc-Signature header in the HTTP or HTTPS request initiated by Real-Time Communication (RTC). If the two values are different, the request is invalid.

Callback retry

After Alibaba Cloud initiates a callback request, the callback is considered successful only if the HTTP status code 200 is returned by your business server. If a callback fails, ApsaraVideo Live resends the callback request 7 times at intervals of 1 second, 2 seconds, 5 seconds, 10 seconds, 60 seconds, 120 seconds, and 300 seconds. A callback record is generated each time a callback request is resent.

Exception handling

A keep-alive mechanism is implemented between clients that have joined a channel or started stream ingest and the Alibaba Cloud server. If the server does not receive heartbeat information from a client for 90 seconds, the server considers that the client timed out and the user left the channel and then fires callbacks. Heartbeats fail to be detected if a network disconnection occurs or the application accidentally exits.