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

HTTP callback mechanism

  1. You must deploy an HTTP service to receive callback messages and specify a callback URL in the ApsaraVideo VOD console.
  2. 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.
  3. 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.
  4. 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

The following table lists the authentication parameters that can be added to HTTP callback request headers.
ParameterDescription
X-VOD-TIMESTAMPThe 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-SIGNATUREThe signature string, which is an MD5 value of 32 characters. 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.
ParameterExampleDescription
Callback URLhttps://www.example.com/your/callbackThe callback URL that you specified.
X-VOD-TIMESTAMP1519375990The 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.
AuthKeyTest123The 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 Configuration Management > Media Processing > Callback. 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.
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 operations to switch the keys.
  1. Define a new value for the AuthKey parameter.
  2. Upgrade the server that receives the callback message to support authentication based on the old and new keys.
  3. Replace the value of AuthKey with the new value in the ApsaraVideo VOD console.
  4. After a period of time, remove the support for the old key from the server that receives the callback message.
  5. The key is switched.

Usage notes

Prerequisites

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

  1. 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 Configuration Management > Media Processing > Callback. 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.
      HTTP callback
    • 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 to HTTP and specify other request parameters such as CallbackURL and EventTypeList.
      • 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 the MessageCallback field in UserData to configure only HTTP callbacks. You must enable global event notifications and configure related events for the HTTP callback settings to take effect.
  2. 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.

  3. 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.