ApsaraVideo VOD:HTTP callbacks

HTTP callback mechanism

1. You 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 the callback URL. The event notification is delivered in the HTTP body.

3. Your HTTP service authenticates the signature of the HTTP POST request. If the authentication is successful, the service returns the HTTP status code 200 to indicate a successful callback. If another status code is returned or the request times out, the callback has failed. For more information about the authentication process, see HTTP callback authentication process.

4. If the callback is successful, your configured callback URL receives the event notification. If the callback fails, ApsaraVideo VOD retries the callback twice. If all three attempts fail, ApsaraVideo VOD discards the event notification. For more information about callback validation and retries, see Callback validation and retries.

How to use

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. Event notification configurations are region-specific. You can configure a separate callback method and webhook address for each region.

• HTTP callbacks support multiple webhook addresses to support different development environments. For more information, see Configure multiple webhook addresses.

Procedure

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

   Note

   Callbacks configured in the ApsaraVideo VOD console are global configurations for the service. You can use the OpenAPI to configure global callbacks or override the configuration for a single request.

   Configure HTTP callbacks in the 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 the target region from the region drop-down list to the right of Workbench.

   4. Configure the Callback Settings.

      1. Next to Callback Settings, click Modify.

      2. Configure the callback parameters.

         Parameter Name	Description
         Callback Method	Select HTTP Request.
         Callback URL	Set the webhook address to receive callback messages. When a callback event occurs, the ApsaraVideo VOD server sends an HTTP POST request to this address. The URL can be up to 256 bytes in length. Multiple URLs are not supported.
         Callback Events	Select the event types for which you want to receive notifications, as needed. For more information about the event types supported by ApsaraVideo VOD and the details of each event notification, see Event list. Note If you select AI Processing Completed, notifications are triggered for all AI events, such as AIMediaAuditComplete, AIMediaDNAComplete, and AIVideoTagComplete.

      3. Click OK.

   5. Optional: Configure Callback Authentication.

      If the callback method is HTTP Request, you can add authentication parameters to the HTTP or HTTPS request header. This allows the receiving server to perform signature authentication to prevent illegal or invalid requests.

      1. In the Callback Authentication section, click Modify.

      2. Set the authentication key.

         This authentication key is the AuthKey field in the signature algorithm. 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 to complete the configuration.

      4. After you enable callback authentication, configure the corresponding authentication logic on your receiving HTTP or HTTPS server. For more information, see HTTP callback authentication process.

   Configure HTTP callbacks using OpenAPI

   You can call different operations to configure global callbacks or override the configuration for a single request.

   • Global configuration: Call the Set Event Notification Configuration operation by setting the CallbackType request parameter to HTTP, and configuring other parameters such as CallbackURL and EventTypeList.

   • Per-request override: You can set a webhook address for a single request by specifying the MessageCallback field in the UserData request parameter. This feature is available when you call the following operations to upload media files or submit media processing jobs:

     • CreateUploadVideo

     • CreateUploadImage

     • CreateUploadAttachedMedia

     • UploadMediaByURL

     • RegisterMedia

     • SubmitTranscodeJobs

     • SubmitSnapshotJob

     • SubmitAIMediaAuditJob

     • ProduceEditingProjectVideo

   Note

   When you use the UserData field in MessageCallback to configure a callback, you must first enable global event notifications for ApsaraVideo VOD and configure the corresponding callback event types for the callback configuration to take effect.

2. Trigger a callback event.

   After you configure event notifications, perform operations in ApsaraVideo VOD, such as uploading media assets (audio, video, or images) or submitting media processing jobs (transcoding or snapshots), to trigger callback events.

3. Receive the callback event.

   After a callback event is triggered, if the callback is successful, you can view the event notification in your deployed callback receiving service.

HTTP callback authentication principle

When the callback method is HTTP Request, you can add authentication parameters to the HTTP (including HTTPS) header. This allows the receiving server to authenticate the signature to prevent illegal or invalid requests.

Usage notes

• Enabling HTTP callback authentication is optional but recommended. If you set an authentication key (AuthKey), the callback includes all the necessary information for the receiving server to perform authentication. Setting an AuthKey does not affect existing features, and you can decide whether to perform the validation on your server.

• If you do not set an AuthKey, the HTTP callback feature is not affected.

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

Validation rules for the callback receiving server

• The callback receiving server concatenates the configured callback URL, the value of X-VOD-TIMESTAMP, and the AuthKey. Then, the server calculates the MD5 hash of the concatenated string and compares the result with the value of the X-VOD-SIGNATURE field. If the values do not match, the request is invalid.

• The callback receiving server retrieves the current time and compares it with the time specified by the X-VOD-TIMESTAMP field in the callback request. If the difference exceeds a specified period, such as 5 minutes, the request is considered invalid. The period is defined by the callback receiving server.

  Note

  The time difference may be inaccurate due to issues such as time settings. You can decide whether to perform this validation on the callback receiving server.

AuthKey switching

When you switch the AuthKey, the callback receiving server must support a smooth transition by supporting both the old and new AuthKeys to ensure that the callback feature is not affected. This means that for a period of time, the server must support authentication with both the old and new AuthKeys. The callback receiving server is responsible for handling this transition.

References

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

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