Parameters, rules, and usage notes of HTTP callbacks - ApsaraVideo VOD

This topic describes the mechanism, usage, and authentication principles of HTTP callbacks.

HTTP callback mechanism

You must deploy an HTTP service to receive callback messages and specify a callback URL in ApsaraVideo VOD.
When an event occurs, ApsaraVideo VOD sends an HTTP POST request to the specified callback URL. The content of the notification is included in the HTTP request body.
After an HTTP POST request is sent, the HTTP service performs signature authentication on the request. If the request passes the authentication, the HTTP status code 200 is returned to indicate that the callback is successful. If an HTTP status code other than 200 is returned or the request times out, the callback fails. For more information, see HTTP callback authentication.
If a callback request is successful, the event notification is sent to the callback URL that you specified. If a callback request fails, ApsaraVideo VOD resends the callback request two times. If the callback request fails to be sent after three attempts, ApsaraVideo VOD discards the request. For more information about the retry logic and how to determine successful callbacks, see Callback determination and retries.

How to use HTTP callbacks

Prerequisites

An HTTP or HTTPS service is deployed to receive callback messages.
An Alibaba Cloud account is created and real-name verification is complete. To create an Alibaba Cloud account, visit the Alibaba Cloud official website. For more information, see Create an Alibaba Cloud account.
ApsaraVideo VOD is activated. For more information, see Activate ApsaraVideo VOD.

Usage notes

ApsaraVideo VOD supports multiple service regions. The event notification configurations among regions are independent of each other. You can use different callback methods and callback URLs for different regions.
You can specify multiple HTTP callback URLs to meet your development requirements in different environments. For more information, see Specify multiple callback URLs.

Procedure

Configure HTTP callbacks to receive event notifications.

Note

If you configure event callbacks by using the ApsaraVideo VOD console, the settings take effect globally. You can also call different API operations to configure global callback settings or configure a specific callback in ApsaraVideo VOD.

By using the ApsaraVideo VOD console

Log on to the ApsaraVideo VOD console.
In the left-side navigation pane, choose Configuration Management > Media Processing > Callback.
In the top navigation bar, select the desired region from the drop-down list next to the Workbench button.

Configure callback settings. HTTP回调

On the Callback page, click Modify in the Callback section.

Configure callback parameters. The following table describes the parameters.

Parameter	Description
Callback Method	Select HTTP Request.
Callback URL	Specify a callback URL. After an event that you selected is triggered, ApsaraVideo VOD sends an HTTP POST request to the URL. The URL can be up to 256 bytes in length. You can specify only one URL.
Events	Select the events for which you want to configure callbacks based on your business requirements. For more information about the events supported in ApsaraVideo VOD and event notification content, see Events. Note If you select AI Processing Completed, notifications are sent for all AI events such as AIMediaAuditComplete, AIMediaDNAComplete, and AIVideoTagComplete.

Click OK.

Optional. Configure callback authentication.
If you set the callback method to HTTP Request, you can add authentication parameters to the HTTP and HTTPS request headers. This way, the server that receives callback event notifications can authenticate the signature to prevent illegal or invalid requests.
1. Enable callback authentication or click Modify in the Callback Authentication section.
2. Specify the authentication key.
  The AuthKey field indicates the authentication key. For more information, see Signature algorithm. The key can be up to 32 characters in length and must contain digits, uppercase letters, and lowercase letters.
3. Click OK.
4. After you enable callback authentication, configure the corresponding authentication logic for the HTTP or HTTPS service that you deployed to receive callback messages. For more information, see HTTP callback authentication.

By using the ApsaraVideo VOD API

You can call different API operations to configure global callback settings or configure a specific callback in ApsaraVideo VOD.

To configure global HTTP callback settings, call the SetMessageCallback operation. When you call this operation, set CallbackType to HTTP and specify other request parameters such as CallbackURL and EventTypeList.
To configure a specific HTTP callback, specify the MessageCallback field in UserData when you call API operations. You can call the following API operations to upload media files or submit media processing jobs:

Note

You can specify the MessageCallback field in UserData to configure callbacks. You must enable global event notifications and configure related events for the HTTP callback settings to take effect.

Trigger the event.
After you configure event notifications, you can perform operations, such as uploading audio, video, or image files, to trigger the event. You can also submit media processing jobs, such as transcoding jobs and snapshot jobs, to trigger the event.
View the callback message.
After a callback event is triggered, you can view the event notification in the callback service that you deployed if the callback is successful.

HTTP callback authentication

ApsaraVideo VOD allows you to add authentication parameters to the HTTP and HTTPS request headers. This way, the server that receives callback messages can authenticate the signature to prevent illegal or invalid requests.

Usage notes

You can choose to enable or disable HTTP callback authentication based on your business requirements. We recommend that you enable HTTP callback authentication. If you set the AuthKey parameter, callback requests carry all authentication-related information. The server that receives callback messages uses the information to authenticate callback requests. You can determine whether to enable authentication on the server.
The callback service is not affected even if you do not specify the AuthKey parameter.

Authentication parameters

The following table lists the authentication parameters that can be added to HTTP callback request headers.

Parameter	Description
X-VOD-TIMESTAMP	The UNIX timestamp when the callback request is sent. The value is a 10-digit positive integer that represents the number of seconds that have elapsed since 00:00:00 January 1, 1970.
X-VOD-SIGNATURE	The signature string, which is a 32-character MD5 value. For more information, see the following section.

Signature algorithm

The value of the X-VOD-SIGNATURE parameter is calculated based on the parameters described in the following table.

Parameter	Example	Description
Callback URL	https://www.example.com/your/callback	The callback URL that you specified.
X-VOD-TIMESTAMP	1519375990	The UNIX timestamp when the callback request is sent. The value is a 10-digit positive integer that represents the number of seconds that have elapsed since 00:00:00 January 1, 1970.
AuthKey	Test123	The key can be up to 32 characters in length and must contain digits, uppercase letters, and lowercase letters.

Concatenate the preceding three parameters by separating them with vertical bars (|). Then, calculate the MD5 hash value of the concatenated string. Sample code:

MD5Content = Callback URL|X-VOD-TIMESTAMP|AuthKey
X-VOD-SIGNATURE = md5sum(MD5Content)

Sample code for calculating X-VOD-SIGNATURE:

X-VOD-SIGNATURE = md5sum(https://www.example.com/your/callback|1519375990|Test123) = c72b60894140fa98920f1279219b****

Authentication rules

The server that receives the callback message concatenates the callback URL, X-VOD-TIMESTAMP, and AuthKey into a string and calculates the MD5 hash value of the string. Then, the server compares the MD5 hash value with the value of X-VOD-SIGNATURE. If the two values are different, the request is considered invalid.
The server that receives the callback message obtains the current time and calculates the difference between the current time and the time specified by the X-VOD-TIMESTAMP parameter in the callback request. If the time difference exceeds the value set by the server, such as 5 minutes, the request is considered invalid.
Note
The calculated time difference may be inaccurate due to incorrect time settings. You can decide whether to enable time difference verification on the server based on your business requirements.

AuthKey switching

If you change the value of the AuthKey parameter, the server that receives the callback message must support authentication based on the old and new keys to ensure that the callback service is not affected. In this case, the server can implement authentication based on the old and new keys.

We recommend that you perform the following steps to switch the keys:

Define a new value for the AuthKey parameter.
Upgrade the server that receives the callback message to support authentication based on the old and new keys.
Replace the value of AuthKey with the new value in the ApsaraVideo VOD console.
After a period of time, remove the support for the old key from the server that receives the callback message.
Switch the key.

References

For more information about the comparison between HTTP callbacks and MNS callbacks, see Comparison between HTTP callbacks and MNS callbacks.
If issues occur when you configure HTTP callbacks, see FAQ about event notifications.