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 the ApsaraVideo VOD console.
- 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 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 about signature authentication, 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 the "Callback determination and retries" section of the Overview topic.
HTTP callback authentication
ApsaraVideo VOD allows you to add a specific signature header to HTTP and HTTPS callback requests. 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
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 an MD5 value of 32 characters. For more information, see the following section. |
Signature algorithm
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 authentication key that you specified. You can perform the following operations to specify an authentication key: Log on to the ApsaraVideo VOD console. In the left-side navigation pane, choose . On the page that appears, turn on Callback Authentication. In the dialog box that appears, specify an authentication key. The key can be up to 32 characters in length and must contain digits, uppercase letters, and lowercase letters. |
MD5Content = Callback URL|X-VOD-TIMESTAMP|AuthKey
X-VOD-SIGNATURE = md5sum(MD5Content)
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.
- 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.
- The key is switched.
Usage notes
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 about how to create an Alibaba Cloud account, see Create an Alibaba Cloud account.
ApsaraVideo VOD is activated. For more information, see Activate ApsaraVideo VOD.
Limits
ApsaraVideo VOD supports multiple storage 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 upload videos to different regions. After a video is processed, such as uploaded or transcoded, ApsaraVideo VOD notifies you of the processing results based on the callback configurations for the regions and pushes messages to your MNS queues.
Procedure
- Configure HTTP callbacks to receive event notifications.
Specify a callback URL and events for which you want to configure callbacks in ApsaraVideo VOD based on your business requirements. For more information about supported events and event notification content, see Events.
You can configure event notifications by using the ApsaraVideo VOD console, API, or SDK. The following section describes how to configure event notifications:- By using the ApsaraVideo VOD console
Log on to the ApsaraVideo VOD console. In the left-side navigation pane, choose . On the Callback page, specify a callback URL and the events for which you want to configure callbacks. For more information, see Configure callbacks.
Note- If you configure event callbacks by using the ApsaraVideo VOD console, the settings take effect globally.
- If you select AI Processing Completed, notifications are sent for all AI events such as AIMediaAuditComplete, AIMediaDNAComplete, and AIVideoTagComplete.
- By using the ApsaraVideo VOD API or SDK
You can call different API operations to configure global HTTP callback settings or configure a specific HTTP callback in ApsaraVideo VOD.
- To configure global HTTP callback settings, call the SetMessageCallback operation. When you call this operation, set
CallbackType
toHTTP
and specify other request parameters such asCallbackURL
andEventTypeList
. - To configure a specific HTTP callback, perform the following operations: specify the MessageCallback field in
UserData
when you call API operations such as CreateUploadVideo and SubmitTranscodeJobs. MessageCallback specifies the callback URL.
Note You can specify theMessageCallback
field inUserData
to configure only HTTP callbacks. You must enable global event notifications and configure related events for the HTTP callback settings to take effect. - To configure global HTTP callback settings, call the SetMessageCallback operation. When you call this operation, set
- By using the ApsaraVideo VOD console
- 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.
References
- For more information about the differences between HTTP callbacks and MNS callbacks, see the "Comparison between HTTP callbacks and MNS callbacks" section of the Overview topic.
- If issues occur when you configure HTTP callbacks, see FAQ about event notifications.