Creates a callback to subscribe to channel or user events.
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.
Debugging
Request parameters
Parameter | Type | Required | Example | Description |
Action | String | Yes | CreateEventSub | The operation that you want to perform. Set the value to CreateEventSub. |
AppId | String | Yes | 9qb1**** | The application ID. |
ChannelId | String | No | 123333 | The channel ID. You can call the ListEventSub operation to query the ID of a subscribed channel. Note
|
Users.N | String | No | user1 | The user whose events you want to subscribe to. If you leave this parameter empty, the events of all users in the channel are subscribed to, including the events of the streamer and viewers. Specify this parameter in the following format:
|
Events.N | String | Yes | ChannelEvent | The type of the event. Valid values:
|
CallbackUrl | String | Yes | http://****.com/callback | The callback URL. For more information about the content of the messages that are sent to the callback URL, see the Callback section in this topic. |
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
Parameter | Type | Required | Description |
UserId | string | Yes | The user ID. |
SessionId | string | Yes | The session ID. |
EventTag | string | Yes | The event. Valid values: Join: The user joined the channel. Leave: The user left the channel. PublishVideo: The user ingested a video stream. PublishAudio: The user ingested an audio stream. PublishScreen: The user ingested a stream for screen sharing. UnpublishVideo: The user stopped ingesting a video stream. UnpublishAudio: The user stopped ingesting an audio stream. UnpublishScreen: The user stopped ingesting a stream for screen sharing. Roleupdate: The role of the user was changed. |
Timestamp | number | Yes | The timestamp when the event occurred. |
Reason | integer | Yes | The reason for joining or leaving the channel. This parameter is available only if the event is a Join event. Valid values: 1: The user joined or left the channel as needed. 2: The user reconnected to the channel to join the channel again when the user already existed in the channel. 3: The user performed stream relay across channels. 4: The user left the channel due to a timeout. 5: The user started a new session and was forced to go offline in the current session. 6: The user was kicked out of the channel. 7: The channel was closed. |
Role | integer | Yes | The role of the user. Valid values: 1: streamer 2: viewer |
CurrentMedias | integer | Yes | The type of the stream. Valid values: 1: audio 2: video 3: screen sharing |
Parameters of a channel event
Parameter | Type | Required | Description |
EventTag | string | Yes | The event. Valid values: Open: The channel was opened. Close: The channel was closed. |
Timestamp | number | Yes | The timestamp when the event occurred. |
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
Parameter | Type | Example | Description |
RequestId | String | 760bad53276431c499e30dc36f6b26be | The request ID. |
SubscribeId | String | ad53276431c**** | The subscription ID. |
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
HttpCode | Error code | Error message | Description |
400 | InputInvalid | %s. | The specified parameters are invalid. |
400 | QuotaLimitError | %s. | For each application ID, you can create up to 20 subscriptions and only one all-channel subscription is allowed. |
400 | ErrorInvalidCallBackUrl | %s. | The value specified for the CallbackUrl parameter is invalid. Check the callback URL and try again. |
403 | NoAuth | %s. | You do not have the required permissions. |
404 | ResourceNotExist | %s. | The requested resource does not exist. Check whether the resource exists and try again. |
500 | ServerError | %s. | An unknown error occurred. Try again later or submit a ticket. |
For a list of error codes, see Service error codes.