:CreateEventSub

Usage notes

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. Requests that exceed this limit are dropped and you may experience service interruptions. We recommend that you take note of this limit when you call this operation.

Request parameters

Users.1=****
Users.2=****
......

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": "80331631628db0d1",    // The user ID.
          "EventTag": "Publish",    // The event. Valid values: Join, Leave, Publish, Unpublish, and Roleupdate.
          "SessionId": "0dr15rrnhkz0jnvz6o8sxo01hoondhu1", // 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": "8888889999",
          "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 who have joined a channel or started stream ingest and the Alibaba Cloud server. If the server does not receive heartbeat information from clients for 90 seconds, the server considers the client timed out and the user left the channel and fires callbacks. Heartbeats may fail to be detected because a network disconnection occurs or the application accidentally exits.

Response parameters

Examples

Sample requests

http(s)://[Endpoint]/?Action=CreateEventSub
&AppId=9qb1****
&ChannelId=123333
&Users=["user1"]
&Events=["ChannelEvent"]
&CallbackUrl=http://****.com/callback
&<Common request parameters>

Sample success responses

XML format

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

<CreateEventSubResponse>
    <RequestId>760bad53276431c499e30dc36f6b26be</RequestId>
    <SubscribeId>ad53276431c****</SubscribeId>
</CreateEventSubResponse>

JSON format

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

{
  "RequestId" : "760bad53276431c499e30dc36f6b26be",
  "SubscribeId" : "ad53276431c****"
}

Error codes

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