ApsaraVideo VOD supports HTTP callbacks and Alibaba Cloud Message Service (MNS) callbacks. This topic describes the event types, callback methods, callback configurations, callback protocols, and common callback parameters for event notifications. This topic also describes the retry rules, FAQ, and how to determine successful callbacks.
ApsaraVideo VOD supports event notifications for multiple regions. You can specify callback methods and callback URLs for event notifications for each region. You can upload and store videos in different regions. After the videos are processed, ApsaraVideo VOD notifies you of the processing results based on the callback method and callback URL that you specified for the region.
Only HTTP URLs are returned in the callback body. HTTPS URLs are not supported. If you want HTTPS URLs to be returned, see the solution described in the FAQ about event notifications topic.
ApsaraVideo VOD supports HTTP callbacks (HTTPS compatible) and MNS callbacks to obtain event notifications.
HTTP callbacks (HTTPS compatible):
HTTP callbacks are automatically returned for you to obtain event notifications in ApsaraVideo VOD. 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. Then, the notification content is returned in the HTTP response body.
You must obtain MNS callbacks from MNS. You must authorize ApsaraVideo VOD to access MNS, create a queue or use an existing queue in the MNS console, and then configure event notifications in ApsaraVideo VOD. When an event occurs, ApsaraVideo VOD pushes the callback message to the queue. You must obtain the callback message from MNS. For more information about how to create a queue and receive callback messages in the MNS console, see Manage queues in the console.
Comparison between HTTP callbacks and MNS callbacks
MNS callback (recommended)
If the HTTP message receiving service is abnormal, messages may be lost. For example, messages may be lost if the service is interrupted or restarts.
MNS callbacks are more reliable than HTTP callbacks. Almost all MNS callbacks succeed if they are configured properly.
If you use HTTP callbacks, all users can send callback requests to the specified callback URLs. However, you can use callback authentication to reject invalid requests and enhance the security of HTTP callbacks.
For more information, see HTTP callback authentication.
MNS callbacks are more secure because only authorized users can read and write message queues.
HTTP callbacks are more convenient than MNS callbacks because you need only to deploy a message receiving service to use HTTP callbacks.
To use MNS callbacks, you must activate and configure MNS, and develop and deploy an application to consume messages.
Request: HTTP POST requests are sent and the message body is in the JSON format. For more information about the message body for each event, see the Event types section of this topic.
Response: ApsaraVideo VOD ignores the response body.
Callback messages are in the JSON format. For more information about the message body for each event, see the Event types section of this topic.
Common callback parameters
The time when the event was generated. The time follows the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format and is displayed in UTC.
The type of the event.
The ID of the video file.
The result of the event. Valid values:
If the UserData parameter is specified in the upload or submit operations and the Extend field is included, user data is returned in pass-through mode when the callback is returned. The value of this field can be up to 512 bytes in length.
Callback determination and retries
After an HTTP callback request is sent, ApsaraVideo VOD checks the HTTP status code in the response returned by the HTTP message receiving service. If the HTTP status code 200 is returned, the callback is successful. If an HTTP status code other than 200 is returned or no response is returned within 5 seconds, the callback fails. ApsaraVideo VOD checks only the HTTP status code in responses and ignores the response body.
If the callback request fails to be sent due to incorrect configurations, such as incorrect callback URLs or an abnormal HTTP message receiving service, ApsaraVideo VOD retries to send the callback request two more times. If the callback request fails to be sent after three attempts, ApsaraVideo VOD discards the request.
If you use MNS callbacks, ApsaraVideo VOD determines that an MNS callback is successful when the message is pushed to the MNS queue.
If the message fails to be pushed to the queue due to incorrect configurations, ApsaraVideo VOD retries to push the message two more times. For example, the callback message fails to be sent if ApsaraVideo VOD is not authorized to access MNS, the MNS endpoint is not a public endpoint, or the queue name is incorrect. If the message fails to be pushed after three attempts, ApsaraVideo VOD discards the message.
When a callback fails, ApsaraVideo VOD retries the callback at an interval of 1 second. If the callback fails after three attempts, ApsaraVideo VOD discards the request. We recommend that you use MNS callbacks because they are more reliable than HTTP callbacks. Almost all MNS callbacks succeed if they are configured properly.
HTTP callbacks and MNS callbacks are configured differently. You can use the ApsaraVideo VOD console, API, or SDK to configure HTTP callbacks and MNS callbacks. For more information, see HTTP callback authentication and Reliable MNS event notification.
The following table describes the event types for which event notifications are provided in ApsaraVideo VOD.
For more information about commonly asked questions, such as how to obtain HTTPS URLs from callback messages and how to specify multiple callback URLs, see FAQ about event notifications.