All Products
Search
Document Center

HTTP callback authentication

Last Updated: Jul 11, 2019

Overview

ApsaraVideo for VOD allows you to add a specific signature header to HTTP (or HTTPS) callback requests. The callback message receiving server verifies the signature to prevent illegal or invalid requests.

Authentication parameters

The following table lists the specific authentication parameters added to HTTP callback requests.

Parameter Description
X-VOD-TIMESTAMP The UNIX timestamp when the callback request is sent. Valid value: a positive integer consisting of 10 digits. This parameter represents the number of seconds that have elapsed since 00:00:00 on January 1, 1970.
X-VOD-SIGNATURE The signature string, which is an MD5 hash consisting of 32 characters. For more information, see the signature algorithm.

Signature algorithm

The value of the X-VOD-SIGNATURE parameter is calculated based on the parameters listed in the following table.

Parameter Description
Callback URL The URL to which callback requests are sent.
X-VOD-TIMESTAMP The UNIX timestamp when the callback request is sent. Valid value: a positive integer consisting of 10 digits. This parameter represents the number of seconds that have elapsed since 00:00:00 on January 1, 1970.
PrivateKey The preset signature key.

Concatenate the preceding three parameters by separating them with vertical bars (|), and then calculate the MD5 hash of the concatenated string. The MD5 hash is used as the value of the X-VOD-SIGNATURE parameter.

  1. MD5Content = Callback URL|X-VOD-TIMESTAMP|PrivateKey
  2. X-VOD-SIGNATURE = md5sum(MD5Content)

For example:

  • Callback URL: https://www.example.com/your/callback
  • X-VOD-TIMESTAMP: 1519375990
  • PrivateKey: test123

The value of the X-VOD-SIGNATURE parameter is calculated as follows:

  1. Note: Use vertical bars (|) to separate the parameters required for the calculation.
  2. X-VOD-SIGNATURE = md5sum(https://www.example.com/your/callback|1519375990|test123) = 9be6123e72b935804d3daf3d93335a65

Verification rules on the callback message receiving server

  1. The callback message receiving server concatenates the callback URL, X-VOD-TIMESTAMP, and PrivateKey into a string and calculates the MD5 hash of the string. Then, the callback message receiving server compares the MD5 hash with the obtained value of the X-VOD-SIGNATURE parameter. If they are different, the callback message receiving server considers that the request is illegal.
  2. The callback message receiving server 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 specified value set by the server (for example, five minutes), the callback message receiving server considers that the request is invalid. (Note: The calculated time difference may be inaccurate due to time settings and other problems. Therefore, the time difference verification is optional. You can decide whether to enable it on the callback message receiving server.)

PrivateKey switching

  1. After the customer changes the value of the PrivateKey parameter, the callback message receiving server needs to support both the old and new keys for a period of time. This ensures that the old and new keys are switched smoothly without affecting the callback service. The customer needs to implement the support for the old key on the callback message receiving server on its own.
  2. The recommended procedure for switching from the old key to the new key is as follows:
    • Define a new value for the PrivateKey parameter.
    • Upgrade the callback message receiving server so that it supports both the old and new keys.
    • Update PrivateKey to the latest value in the ApsaraVideo for VOD console.
    • After a period of time, remove the support for the old key from the callback message receiving server.
    • The switching is completed.

Other precautions

  1. Callback authentication is optional. (We recommend that you enable it). Once PrivateKey is set, callback requests contain all authentication-related content for the callback message receiving server to perform authentication. You can determine whether to enable the authentication on the server.
  2. Customers who have not set PrivateKey can still use the callback service properly.