Webhook management

Create a parameter

1. Go to Workspace > Configuration Management > Marketing Configuration > Webhook Management > Webhook Parameter Management to view the webhook parameter list.

   

2. Click Create Webhook Parameter in the upper-right corner.

3. In the dialog box that appears, configure the parameters. The configuration methods for API-based and constant-based parameters are different:

   • API-based:

     

     Parameter	Description
     Parameter Name	Enter a name for the API.
     Parameter Type	Select API-based.
     API URL	Enter the URL of the API that passes the parameter.
     Parameter Description	Description of input parameters.
     Authentication Method	Select an authentication method: None: No authentication is performed. Key: Authenticates using a key. You must enter the key below.

   • Constant-based:

     

     Parameter	Description
     Parameter Name	You can enter the interface name.
     Parameter Type	Select Constant-based.
     Parameter Description	Enter a description for the parameter.
     Parameter Settings	Enter the parameter value and its corresponding display name. When you create a webhook task and select content for a constant-based parameter, the options are shown as display names. Click Add Parameter to add another parameter.

4. Click OK to save the configuration.

Manage parameters

The parameter list provides the following actions:

• Details: Click to view parameter details.

• Edit: Click to edit the parameter. The configuration steps are the same as those for creating a parameter.

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

HTTP endpoint server

To integrate with Quick Audience webhooks, you must develop an HTTP server. Quick Audience sends POST requests with a timeout of 10 seconds. The POST requests sent by Quick Audience and the receipt requests sent from your system must include the following required common parameters.

Example request URL:

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

Authentication method

Authentication is performed using a key. When you configure the webhook, you can enable authentication and enter a key.

Quick Audience uses the key you provide, along with the `timestamp` and `nonce` URL parameters, to generate an HmacSHA256Hex signature. This signature is passed in the `X-QA-Hmac-Signature` request header. When your service receives the request, it must perform the same HmacSHA256Hex calculation using the URL parameters and the key configured for the webhook. If the calculated value matches the signature from the request header, you can verify that the request originated from Quick Audience. The same process applies when your system reports receipts.

Example signature algorithm:

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};
    StringBuffer sb = new StringBuffer();
    // Sort the strings
    Arrays.sort(array);
    for (int i = 0; i < 3; i++) {
        sb.append(array[i]);
    }
    return sb.toString();
}

Webhook request

The request is an HTTP POST request that is sent from Quick Audience to your system. The request body contains the trigger information for a single user.

POST header information:

After you read the header information, you must decode it using `java.net.URLDecoder#decode(java.lang.String, java.lang.String)` with UTF-8 encoding. The header may contain the following information:

processId=Automated marketing campaign ID
processName=Automated marketing campaign name
processSchedulerId=ID for each recurring schedule of the automated marketing campaign
processSchedulerName=Name for each recurring schedule of the automated marketing campaign: a string concatenating the campaign ID and the schedule time
processSchedulerStartTime=Start time of the automated marketing campaign schedule, in UNIX timestamp format
processNodeId=Automated marketing campaign node ID (the same for each schedule)
processNodeName=Automated marketing campaign node name (the same for each schedule)
activityId=ID of the main activity associated with the sub-activity
activityName=Name of the main activity associated with the sub-activity
subActivityId=Associated sub-activity ID
subActivityName=Associated sub-activity name

jobId=Deprecated: Same as processId. Use processId instead.
jobName=Deprecated: Same as processName. Use processName instead.
nodeId=Deprecated: Same as processNodeId. Use processNodeId instead.
nodeName=Deprecated: Same as processNodeName. Use processNodeName instead.
taskStartTimestamp=Deprecated: Same as processSchedulerStartTime, in UNIX timestamp format. Use processSchedulerStartTime instead.
processInstanceId=Deprecated: For backward compatibility. Same as processSchedulerId.
processInstanceName=Deprecated: For backward compatibility. Same as processSchedulerName.
processInstanceStartTime=Deprecated: For backward compatibility. Same as processSchedulerStartTime.

taskId=Field does not exist. Same as processNodeInstanceId. Not compatible.
processNodeInstanceId=Field does not exist. Not compatible.
processNodeInstanceStartTime=Field does not exist. Not compatible.
nodeStartTimestamp=Field does not exist. Same as processNodeInstanceStartTime. Not compatible.

Example POST body structure (This example is for a single user. A batch typically contains 1 to 100 users):

[
    {
        "user_profile": {
            "target_type": "OPEN_ID",
            "target_id": "1917810",
            "customer_id": "Unique customer ID. Use this ID to report events."
        },
        "params": {
            "define_item1": "Coupon ID",
            "define_item2": "Example coupon content. The user's address is Beijing." // Beijing is the value filled in for the ${city} variable.
        },
        "callback_params": {
            "task_id": "Deprecated",
            "Webhook_id": "13312313",
            "send_time": "1625037472000",
            "nodeId": "Node ID",
            "instanceId": "Instance ID",
            "actionId": "Action execution instance ID",
            "customerId": "User ID, customerId",
        },
        "process_info": {
            "processInstanceId": "New version: Instance ID for each user's automated marketing campaign within a schedule.",
            "processInstanceStartTime": "New version: Start time of the instance for each user's automated marketing campaign within a schedule, in UNIX timestamp format.",
            "processNodeInstanceId": "New version: Automated marketing campaign node instance ID (different each time).",
            "processNodeInstanceStartTime": "New version: Start time of the node instance for each user's automated marketing campaign within a schedule, in UNIX timestamp format.",
            "groupId":"New version: Group ID",
            "groupName":"New version: Group name"
        }
    }
]

Supported user ID types:

After your system receives the request, it must return a response to Quick Audience.

Response body format:

{
 "code":"OK",      // Request status code. "OK" (uppercase) indicates success. Other values are error codes defined by your system.
  "message":"",    // Description of the status code. Optional.
}

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

Webhook parameters are available in several types. The following figure shows the differences between these types and their usage.

Where:

• Constants and APIs are two methods for assigning values to String (Parameter Call) type parameters.

• Variables are inserted into Text type parameters, and their content can be different for each user.