Webhook Management

Create a parameter

1. In the left-side navigation pane, choose Workspace > Configuration Management > Marketing Configuration > Webhook Management > Webhook Parameter Management.

   

2. In the upper-right corner, click Create Webhook Parameter.

3. In the dialog box, configure the parameters. The methods differ for constant-based and interface-based parameters:

   • Interface-based:

     

     Parameter	Description
     Parameter Name	Enter a name for the interface.
     Parameter Type	Select Interface-based.
     Interface URL	Enter the URL of the interface that passes the parameters.
     Parameter Description	Describe the input parameters for this interface.
     Authentication Method	Select an authentication method: None: No authentication. Key: Authenticates using a key. Enter the key below.
     Associate with system parameters	Select an associated parameter: No: Do not associate. Yes: Parameter value settings (add up to 20): Parameter name: Must be in English and can contain English letters, digits, and underscores. It cannot be empty and must be no more than 32 characters long. Display name: No more than 32 characters. Parameter value: Drop-down list options: Current logon user information, Current user's row-level permissions. Associated parameter selection: The drop-down list displays available system parameters.
     Associate with other parameters	Select an associated parameter: No: Do not associate. Yes: Parameter value settings (add up to 20): Parameter name: Must be in English and can contain English letters, digits, and underscores. It cannot be empty and must be no more than 32 characters long. Display name: No more than 32 characters. Parameter value: Drop-down list options: Associated parameter selection, Manual input. Associated parameter selection The drop-down list displays all parameters under Parameter Management. If an interface-based parameter requires a cascading relationship, the interface must contain the relationship between the parameters. Manual input: If you select this, you can manually enter multiple parameter values. To pass multiple values for one parameter, enter them in a single parameter value field. Use the separator agreed upon with the third party. The receiving end will need to split the values.

   • Constant-based:

     

     

     Parameter	Description
     Parameter Name	Enter a name for the interface.
     Parameter Type	Select Constant-based.
     Parameter Description	Enter a description for the parameter.
     Associate with other parameters	Select an associated parameter: No: Parameter value settings (add up to 20). Parameter value: Configure at least one template parameter. The parameter name must be in English, cannot be empty, and must be no more than 32 characters long. Display name: No more than 32 characters. Yes: Parameter value and associated parameter settings (add up to 20).

4. Click OK to complete the configuration.

Manage parameters

The parameter list provides the following actions:

• Details: Click to view parameter details.

• Edit: Click to edit the parameter. The procedure is the same as creation.

• Delete: Click and then confirm in the dialog box to delete the parameter. You can only delete parameters that are not currently in use.

HTTP endpoint server

Develop an HTTP server to receive POST requests from Quick Audience (10-second timeout). Both POST and receipt requests must include these URL parameters.

Sample request URL:

{webhook_configured_url}?timestamp=1631865523&nonce=2e6eceb5737b473284c930c8ef79090e

Authentication method

When authentication is enabled, enter a key during webhook configuration.

Quick Audience signs each request by applying HmacSHA256Hex to the key, `timestamp`, and `nonce` parameters, then passes the signature in the `X-QA-Hmac-Signature` header. Your service verifies requests by computing the same signature and comparing values. The same logic applies to receipt reports.

Sample signature algorithm:

import org.apache.commons.codec.digest.HmacUtils;

public String makeSignature(String key, String timestamp, String nonce) {
    String str = generateStr(key, timestamp, nonce);
    return HmacUtils.hmacSha256Hex(key, str.replaceAll("\\s+", ""));
}

/**
 * Concatenate the strings to be signed.
 */
public static String generateStr(String key, String timestamp, String nonce) {
    String[] array = new String[]{key, timestamp, nonce};
    StringBuilder sb = new StringBuilder();
    Arrays.sort(array);/* Sort the strings */
    for (int i = 0; i < 3; i++) {
        sb.append(array[i]);
    }
    return sb.toString();
}

Webhook request

Quick Audience sends an HTTP POST with trigger information for a single user. All field values are converted to strings.

Sample POST body structure (for a single user; each batch typically contains 1 to 100 users):

[
    {
        "user_profile": {
            "target_type": "OPEN_ID",
            "target_id": "1917810",
            "customer_id": "The unique ID of the customer. Use this ID to report events."
        },
        "params": {
            "define_item1": "Coupon ID",
            "define_item2": "Sample coupon content. The user's address is Beijing."
        },
        "callback_params": {
            "webhook_id": "13312313",
            "send_time": "1625037472000",
            "nodeId": "Node ID",
            "instanceId": "Instance ID",
            "batchId": "The ID of the action execution batch. Can be used as an idempotency ID for the batch.",
            "actionId": "The ID of the action execution instance. Can be used as an idempotency ID for a single item.",
            "customerId": "User ID, customerId"
        },
        "process_info": {
            "processInstanceId": "New version: The journey instance ID for each user in the journey epoch.",
            "processInstanceStartTime": "New version: The start time of the journey instance for each user in the journey epoch, in UNIX timestamp format.",
            "processNodeInstanceId": "New version: The journey node instance ID (different each time).",
            "processNodeInstanceStartTime": "New version: The start time of the journey node instance for each user in the journey epoch, in UNIX timestamp format.",
            "groupName":"nodeId:nodeName:groupResult(node.result),groupName(node.resultExt);nodeId:nodeName:groupResult(node.result),groupName(node.resultExt)",
            "@comment":{
              "groupName" : "Node ID:Node name (configured on the interface):Group result (percentage of the random group, two decimal places):Group name (configured on the interface); separate multiple entries with semicolons."
            }
        }
    }
]

Supported ID types:

Your service must return a response to Quick Audience.

Response body format:

{
 "code":"OK",      //Request status code. OK indicates that the request was successful. The value must be in uppercase. Other values are custom error codes defined by the integrated party.
  "message":"",    //Description of the status code. This is not required.
}

Report receipts

After executing the task, your service reports a receipt with the delivery status.

API description

The `WebHookCallBackMessage` structure is as follows:

Sample receipt report message:

[
 {
 "msg_id": "Unique ID provided by the business side",
 "status": "Receipt status",
 "cst_id": "Customer ID, customerId",
 "send_time": "Receipt sending time, in UNIX timestamp format",
 "callback_params": {
 "return_parameters_as_is": "Return the parameters from the call as-is"
   }
 }
]

API response

Sample request:

curl --location 'https://quicka.aliyun.com/restapi/marketing2/webhook/receiveWebHookCallBack?timestamp=1755848301481&nonce=abc' \
--header 'X-QA-Hmac-Signature: 5d41402abc4b2a76b9719d911017c592' \
--header 'Content-Type: application/json' \
--data '[]'

Sample response:

{
 "code": 200,
 "message": "Success"
}

What is the difference between webhook parameters, variables, constants, and interfaces?

A: Webhook parameters have multiple types. The following figure shows their differences and how to use them.

Specifically:

• Constants and interfaces are two methods for assigning values to string-type parameters.

• Variables are inserted into text-type parameters, and their content is dynamic, changing for each user.