Quick Audience:Webhook Management

Create parameters

1. Choose Workspace> Configuration Management > Marketing Configuration > Webhook Management > Webhook Parameter Management.

   

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

3. Configure parameters in the pop-up window. The configuration methods of constant and API parameters are different:

   • API Type:

     

     Item	Example value
     Parameter	Enter the API name.
     Parameter Type	Select API Type.
     References	Enter the address of the API where the parameters are passed.
     Description	The description of the input parameter.
     The authentication method.	Select an authentication method: None: No authentication is performed. Key: The verification key is used for authentication. You need to enter the key below.
     Whether to associate other parameters	Select associated parameters: No: not associated Yes: Parameter value settings (You can add multiple parameters, up to 20): Parameter Name: The parameter name must be in English, and can be up to 32 characters in length and can contain letters, digits, and underscores. Display name: up to 32 characters Parameter value: Drop-down options, supported options: associated parameter selection, manual input Associated Parameter Selection Drop-down full parameters under parameter management If you need to set a cascade relationship for API-type parameters, the API must contain the cascade relationship between parameters. Manual Input: If you select Manual Input, you can manually enter multiple parameter values. If you need to pass multiple values for one parameter, you can fill in one parameter value, separate multiple values with the delimiter agreed by the three parties, and separate them after receiving

   • Constant type:

     

     

     Item	Example value
     Parameter	Enter the API name.
     Parameter Type	Select Constant Type.
     Description	The description of the input parameter.
     Whether to associate other parameters	Select associated parameters: No: parameter value setting (multiple can be added, up to 20) Parameter Value: At least one template parameter is configured. The parameter name must be in English and cannot be empty. The parameter name must be up to 32 characters in length. Display name: up to 32 characters Yes: parameter values and associated parameter settings (you can add multiple parameters, up to 20)

4. Click OK.

Parameter management

The parameter list provides the following action buttons:

• Details: Click it to view the parameter details.

• Edit: Click it to edit the parameters. The configuration method is the same as when you created the parameter.

• Delete: Click to delete the parameter. In the dialog box that appears, click OK. You can delete only the parameters that are not in use.

HTTP Endpoint Server

To connect to the Webhook of Quick Audience, you need to develop an HTTP server. Quick Audience initiates a Post request with a timeout period of 10 seconds. The following table provides common parameters for Post requests initiated by Quick Audience and receiving requests. The parameters are required.

Sample request URL:

{Webhook configured url}?timestamp=1631865523&nonce=2 e6eceb5737b473284c930c8ef79090e

The authentication method.

The key is used for authentication. Authentication is enabled during Webhook configuration, and the user fills in the key.

Quick Audience uses the timestamp and nonce request parameters the key and URL to sign the HmacSHA256Hex signature and generate a signature. The signature is passed to the request header for authentication. After your service receives the request, it uses the HmacSHA256Hex algorithm to encrypt the request based on the URL parameters and the key that is configured for the Webhook channel. If the calculated value is the same as the signature that is passed in the Request header, you can determine that the request is sent from Quick Audience. The same is applied when submitting a receipt.

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+", ""));
}

/**
 * Sign the concatenation of strings to be processed.
 */
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 strings * /
    for (int i = 0; i < 3; i++) {
        sb.append(array[i]);
    }
    return sb.toString();
}

Webhook Request

The request is an HTTP Post request initiated by Quick Audience to the access party. The request body is the trigger request information of a single user. When sending a request, all fields of any type (such as integers, strings, and text variables) are converted into strings for processing.

Post Body structure example (1 to 100 for a single user):

[
    {
        "user_profile": {
            "target_type": "OPEN_ID",
            "target_id": "1917810",
            "customer_id": "The unique ID of the customer. This ID is required for event reporting"
        },
        "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 batch in which the action is executed. The ID can be the idempotent ID of the batch",
            "actionId": "The ID of the action instance. This parameter can be a single idempotent ID",
            "customerId": "User Id,customerId"
        },
        "process_info": {
            "processInstanceId": "New version: Journey instance ID of each user in a journey cycle",
            "processInstanceStartTime": "New version: the start time of the journey instance for each user in the journey period, in timestamp format",
            "processNodeInstanceId": "New version: journey node instance ID (different each time)",
            "processNodeInstanceStartTime": "New version: The node instance start time of each user's journey in the journey period, in 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 API): grouping result (percentage number of random grouping, two decimal places): group name (configured on the API); separate multiple with semicolon"
            }
        }
    }
]

Supported ID types:

After receiving the request, the access party returns a response message to Quick Audience.

Response body format:

{
 "code":"OK", // Request status code: If OK is returned, the request is successful and must be in uppercase. Otherwise, the error code is returned and is customized by the access party. 
  "message":"", // The description of the status code. This field is optional. 
}

Receipt Reporting

After the access point executes the marketing task, the access point reports the receipt to Quick Audience to feedback the sending result of the marketing message.

For more information, see Quick Audience Open Platform API.

Usage notes

The WebhookCallBackMessage is as follows:

The WebhookCallBackResult is as follows:

The OemImportTaskInfoResponse is as follows:

Sample requests

curl -H "X-QA-Hmac-Signature: 12" -H "Authorization: 57a824b183e54ddbca79170c00dd3f72" -H "Content-Type: application/json" -H "Cookie: csrf_token=f5013e65-0661-41ba-b2ad-8a396a775533" --data-binary "[
    {
        \"msgId\": \"1\"
    }
]" --compressed "http://qa.qa-env09.aliyun.com/openapi/cloud/Webhook/receiveWebhookCallBack?nonce=12&appId=686219778252592361&accessKey=c76f6d5cb309478ab9929616dba64148&timestamp=1718352394665"

Sample response:

• {

  "data": {

  "code": 200,

  "message": "Success"

  },

  "errorCode": null,

  "errorDesc": null,

  "exStack": null,

  "opers": [],

  "solution": null,

  "success": true,

  "traceId": "0ada03af17183523948084322d00b4"

  }

What are the differences between Webhook parameters, variables, constants, and APIs?

A: There are multiple types of Webhook parameters. The following figure shows their differences and usage.

Description:

• Constants and APIs are two ways to assign values to character (parameter call) parameters.

• Variables are inserted in text-type parameters and can be changed by user.