Callback API Description

Updated on 2023-09-27 GMT+08:00

View PDF

The AICC can call back the URL provided by a third-party system to push the current call event to the third-party system.

Due to the continuous evolution of the system, the callback URL of the voice notification can be configured in either of the following methods:

Configuration on the GUI: A tenant administrator can choose Configuration Center > Expansion Management > Voice Notification and set Hang-up Callback URL under VOICE NOTIFICATION CALLBACK CONFIGURATION.
Configuration using the API for creating a voice notification: Pass the request parameter callBackUrl when invoking the API for creating a voice notification.

NOTE:

For configuration of the callback URL on the GUI, no URL authentication is performed, which may cause security risks. Exercise caution when using this mode.
If the callback URL is configured in both methods, the URL passed by the API is preferred. You are advised to pass the callBackUrl parameter using the API, and configure the shared key.

Signature Algorithm of the Voice Notification Callback API

Signature algorithm (authentication) prerequisites
When the URL is passed through the voice notification creation API and Shared Key is configured on the Callback Url Configuration page, verify the signature by referring to this section.

Authentication procedure
1. The following fields are added to the request input parameters of the release event callback API:
  timestamp: current timestamp
  
  nonce: random string
  
  signature: authentication signature
2. After the customer receives the callback request, an authentication signature is generated based on the signature algorithm and will be verified based on signature in the input parameter. The verification passes upon consistency.

Signature string generation method
1. Sort all request parameters (except timestamp, nonce, and signature) in lexicographic order based on parameter names and combine them into a string using commas (,). For example, the parameters in {"b":"2", "a":1} are sorted and combined into the string "a=1, b=2".
2. Generate the values of timestamp (timestamp) and nonce (random string) and combine them with the value of appSecret (shared key configured on the GUI) and the string generated in 1 using underscores (_). The format is {Value of appSecret}_{Value of timestamp}_{Value of nonce}_{String generated in 1}.
3. Encrypt the value into a byte array using the SHA256 algorithm and encode the array using Base64.

Reference code

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

private String generateSinature(TreeMap<String, Object> callbackParametters, String nonce, long timestamp, String appSecret) {
    // {Value of appSecret}_{Value of timestamp}_{Value of nonce}_Parameters
    // For example, the parameters in {"b":"2", "a":1} are sorted and combined into the string "a=1, b=2".
    String paramStr = callbackParametters.toString().replace(" ", "");
    String toSignString = appSecret + "_" + timestamp + "_" + nonce + "_" + 
           paramStr.substring(1, paramStr.length() - 1);
    return Base64.encodeBase64String(tokenByHmacSha256(toSignString.getBytes(StandardCharsets.UTF_8), appSecret));
}

public static byte[] tokenByHmacSha256(byte[] dataBytes, String appSecret) {
    try {
        Mac mac = Mac.getInstance("HmacSHA256");
        byte[] key = appSecret.getBytes(StandardCharsets.UTF_8);
        SecretKeySpec secretKey = new SecretKeySpec(key, "HmacSHA256");
        mac.init(secretKey);return mac.doFinal(dataBytes);
    } catch (Exception e) {
        LOGGER.error("tokenByHmacSha256 failed: ", e);throw new RuntimeException("HmacSha256 run failed.");
    }
}