HTTP callback

How it works

1. Deploy an HTTP service to receive callback messages and configure a callback URL in ApsaraVideo VOD.

2. When an event occurs, the ApsaraVideo VOD server sends an HTTP POST request to this URL, with the event notification content in the request body.

3. Your HTTP service authenticates the signature of the incoming HTTP POST request. If authentication is successful, your service must respond with a 200 status code to indicate a successful callback. Any other status code or a response timeout results in a callback failure. For more information about how authentication works, see How callback authentication works.

4. After a successful callback, your configured callback URL receives the corresponding event notification. If a callback fails, ApsaraVideo VOD retries the request two more times, for a total of three attempts. If all three attempts fail, ApsaraVideo VOD discards the event notification. For details about the callback determination and retry logic, see Callback determination and retries.

How to use HTTP callbacks

Prerequisites

• You have deployed an HTTP or HTTPS service to receive callback messages.

• An Alibaba Cloud account is created and identity verification is complete. To create an Alibaba Cloud account, visit the Alibaba Cloud official website. For more information, see Create an Alibaba Cloud account. For information about identity verification, see Individual identity verification or Enterprise identity verification.

• ApsaraVideo VOD is activated. For more information, see Activate ApsaraVideo VOD.

Usage

• ApsaraVideo VOD is available in multiple service regions. Event notification settings are configured independently for each region. You can configure a separate callback method and callback URL for each service region.

• You can configure multiple callback URLs to meet development needs across different environments. For more information, see Set up multiple callback URLs.

Procedure

1. Configure event notifications for HTTP callbacks in ApsaraVideo VOD.

   Note

   Callback settings configured in the ApsaraVideo VOD console apply globally. You can also use the API to configure global callbacks or implement a single-request override.

   Console

   1. Log on to the ApsaraVideo VOD console.

   2. In the left-side navigation pane, choose Configuration Management > Media Processing > Callback.

   3. In the top navigation bar, select a service region from the drop-down list next to Workbench.

   4. Configure the Callback Settings. In the Callback Authentication section, you can enable authentication and set an authentication key.

      1. Next to Callback Settings, click Modify.

      2. Configure the callback parameters.

         Parameter	Description
         Callback method	Select HTTP Request.
         Callback URL	Enter the URL to receive callback messages. When a callback event occurs, the ApsaraVideo VOD server sends an HTTP POST request to this URL. The URL can be up to 256 bytes in length. You can specify only one URL.
         Events	Select the event types for which you want to receive notifications. For more information about the supported event types and their meanings, see Event list. Note If you select AI Processing Completed, notifications are sent for all AI events, including AIMediaAuditComplete, AIMediaDNAComplete, and AIVideoTagComplete, when any of them completes.

      3. Click OK to save the callback settings.

   5. Optional: Configure Callback Authentication.

      When the callback method is HTTP Request, you can add authentication parameters to the HTTP or HTTPS header. This allows your callback receiver to verify the signature of the request and prevent unauthorized or invalid requests.

      1. Turn on the callback authentication switch, or click Modify next to Callback Authentication.

      2. Set the authentication key.

         This key corresponds to the AuthKey field in the signature algorithm. For more information, see signature algorithm. The key is user-defined, can be up to 32 characters long, and must contain uppercase letters, lowercase letters, and digits.

      3. Click OK to save the configuration.

      4. After enabling callback authentication, you must implement the corresponding authentication logic on your HTTP or HTTPS service that receives the callbacks. For more information, see How callback authentication works.

   API

   You can call different API operations to configure global callbacks or use a single-request override.

   • Global configuration: Call the SetMessageCallback operation. Set the CallbackType parameter to HTTP and configure other parameters such as CallbackURL and EventTypeList.

   • Single-request override: When you call an API to upload media assets or initiate media processing jobs, you can set the callback address for that specific request by specifying the MessageCallback field in the UserData parameter. This applies to the following API operations:

     • Obtain an upload URL and credentials for audio and video

     • Obtain the image upload URL and credentials

     • Obtain an upload URL and credentials for an auxiliary media asset

     • UploadMediaByURL

     • RegisterMedia

     • Submitting an ApsaraVideo Media Processing job

     • Submitting a media snapshot job

     • Submit an automated review job for audio and video

     • Video Compositing

   Note

   To use the MessageCallback parameter in the UserData field for a single-request override, you must first enable global event notifications in ApsaraVideo VOD and configure the corresponding event types. Otherwise, the override settings will not take effect.

2. Trigger a callback event.

   After configuring event notifications, perform an action in ApsaraVideo VOD to trigger an event. For example, you can upload media files (audio, video, or images) or initiate media processing jobs such as transcoding or snapshot creation.

3. Receive the callback event.

   After a callback event occurs, you can view the event notification in your callback receiver if the callback succeeds.

How callback authentication works

When the callback method is HTTP Request, you can add authentication parameters to the HTTP or HTTPS header. This allows your callback receiver to verify the signature of the request and prevent unauthorized or invalid requests.

Usage

• You can choose whether to enable HTTP callback authentication (recommended). If you set an AuthKey (authentication key), all callback requests will include the necessary authentication headers that your callback receiver can use for verification. Setting an AuthKey does not affect existing functionality; you decide whether to enforce validation on your receiver.

• If you do not set an AuthKey, the HTTP callback feature still works as usual.

Authentication parameters

Signature algorithm

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****

Receiver validation rules

• Your callback receiver reconstructs the string by concatenating your configured callback URL, the received X-VOD-TIMESTAMP value, and your stored AuthKey. It then computes the MD5 hash of this string and compares it with the value of the X-VOD-SIGNATURE header. If the values do not match, the request is invalid.

• To prevent replay attacks, your callback receiver can compare its current time with the time in the X-VOD-TIMESTAMP header. If the difference exceeds a specified threshold (for example, 5 minutes), you can consider the request invalid.

  Note

  Due to potential clock skew between servers, this time-based check can be unreliable. You can decide whether to implement this check.

Key rotation

When you rotate your AuthKey, your callback receiver must temporarily support both the old and new keys to ensure a seamless transition and prevent callback failures. Your receiver must handle this dual-key validation logic.

Related documents

• For a comparison between HTTP callbacks and MNS callbacks, see Comparison between HTTP and MNS callbacks.

• If you encounter issues, see FAQ about event notifications.