When you use HTTP requests as the callback method, you can add authentication parameters to HTTP request headers so that the callback-receiving server can verify signatures and reject unauthorized or invalid requests.
Usage notes
Callback authentication is optional but recommended. Enabling or disabling it does not affect existing features. When enabled, callback requests carry authentication information that the receiving server can use to filter out unauthorized requests and enhance security.
Authentication parameters
When you use HTTP requests as the callback method, you can add the following authentication parameters to the HTTP request headers.
|
Parameter |
Description |
|
X-ICE-TIMESTAMP |
The time when the HTTP request was initiated. The value is a UNIX timestamp. |
|
X-ICE-SIGNATURE |
The signature string, which is a 32-character MD5 value. For more information about how to calculate the value of this parameter, see the "Signature calculation" section of this topic. |
Signature calculation
The X-ICE-SIGNATURE value is calculated from the following parameters.
|
Parameter |
Description |
Example |
|
Callback URL |
The callback URL of the HTTP request. |
https://www.example.com/your/callback |
|
X-ICE-TIMESTAMP |
The time when the HTTP request was initiated. The value is a UNIX timestamp. |
1519375990 |
|
Authentication Key |
A user-defined signature key. The key can be up to 32 characters in length and must contain uppercase letters, lowercase letters, and digits. |
Test123 |
Concatenate the three parameters with vertical bars (|), then calculate the MD5 hash of the resulting string. Sample code:
MD5Content = Callback URL|X-ICE-TIMESTAMP|Authentication Key
X-ICE-SIGNATURE = md5sum(MD5Content)Example of calculating X-ICE-SIGNATURE:
X-ICE-SIGNATURE = md5sum(https://www.example.com/your/callback|1519375990|Test123) = c72b60894140fa98920f1279219b****Authentication rules of the server that receives callback messages
-
The receiving server concatenates the callback URL, X-ICE-TIMESTAMP, and authentication key, calculates the MD5 hash, and compares it with the X-ICE-SIGNATURE value. If the two values differ, the request is invalid.
-
The receiving server checks whether the difference between the current time and the X-ICE-TIMESTAMP value exceeds a threshold, such as 5 minutes. If it does, the request is invalid.
Authentication key switching
To switch the authentication key without disrupting the callback service, the receiving server must temporarily support both the old and new keys. We recommend the following steps:
-
Define a new authentication key.
-
Update the server that receives callback messages to support authentication based on both the old and new keys.
-
Configure the new authentication key for callback authentication in the IMS console.
-
After a period of time, remove the support for the old key from the server that receives callback messages.