ApsaraVideo Live:CreateEventSub

Creates a callback for subscribing to channel messages. For example, when creating a callback, you can configure parameters such as the callback URL and event types.

QPS limit

The single-user QPS limit for this operation is 100 calls per second. If the limit is exceeded, API calls are throttled, which may affect your business. Call this operation appropriately.

Callback

The following example shows the content that is called back to the user through the specified CallbackUrl:

Request:

POST /callbackURL

Body
application/json

{
    "MsgId": "Message ID",
    "MsgTimestamp": 12312324, // Unix timestamp when the message is sent
    "SubscribeID": "Subscription ID",
    "AppId":"",     // The AppId that generated this message 
    "ChannelID":"", // The channel that generated this message
    "Contents": [
      {
        "Event": "UserEvent",// Subscription event: user event within a channel
        "UserEvent": {
          "UserId": "80331631628*****",    // User ID
          "EventTag": "Publish",    // Event, including Join, Leave, Publish, Unpublish, Roleupdate
          "SessionId": "0dr15rrnhkz0jnvz6o8sxo0*****", // The SessionID that generated this event
          "Timestamp": 1609854786,    // Unix timestamp when the event occurred
          "Reason": 1, // Reason for joining or leaving. Only available for Join events.
          "Role": 1, //  Role type: streamer or viewer
          "CurrentMedias":"1,2,3"// Stream type: the streams published by the user
        }
      },
      {
        "Event": "ChannelEvent",// Subscription event: channel event
        "ChannelEvent": {
          "ChannelId": "88888****",
          "EventTag": "Open",   // Channel event, including Open and Close
          "Timestamp": 1609854530 // Unix timestamp when the event occurred
        }
      }
   ]
}

Response 
HTTP STATUS 200

UserEvent

ChannelEvent

Callback authentication

The event callback authentication feature is enabled by default. The authentication logic is as follows:

• When ApsaraVideo Live initiates a callback request, the HTTP(S) request header contains the Ali-Rtc-Timestamp and Ali-Rtc-Signature fields for the callback message receiving server to perform signature authentication. The Ali-Rtc-Timestamp value is calculated as follows: Ali-Rtc-Signature=MD5SUM(MD5CONTENT), where MD5CONTENT=Callback domain name|Ali-Rtc-Timestamp value|Authentication Key. The callback domain name is the domain name configured in the callback URL, and the authentication Key is the AppKey generated when the AppId was created.

• When the callback message receiving server receives a callback message, it concatenates the callback domain name, Ali-Rtc-Timestamp value, and authentication Key, calculates the MD5 value to obtain an encrypted string, and then compares the calculated encrypted string with the Ali-Rtc-Signature field value in the HTTP(S) request header initiated by ApsaraVideo Real-time Communication. If they do not match, the request is invalid.

Callback exception retry

When Alibaba Cloud initiates a callback request, the callback is considered successful only when your business server responds with HTTP status code 200. If the callback fails, Alibaba Cloud retries 7 times at intervals of 1 second, 2 seconds, 5 seconds, 10 seconds, 1 minute, 2 minutes, and 5 minutes. Each retry generates a corresponding callback record.

Exception handling

Clients that have joined a channel or are publishing streams maintain a heartbeat keep-alive mechanism with the Alibaba Cloud server. When the heartbeat keep-alive fails because the client loses network connectivity or the app is closed abnormally (failure is determined if no heartbeat is received from the client for 90 seconds), the server determines that the client has timed out and left abnormally, and generates event callbacks for the user stopping stream publishing and leaving the channel.