Quick Audience：Webhook管理

建立參數

1. 選擇工作空間>組態管理>營銷配置>Webhook管理>Webhook參數管理，進入Webhook參數列表。

   

2. 單擊右上方建立Webhook參數。

3. 在彈窗中配置參數，常量型、介面型參數的配置方法不同：

   • 介面型：

     

     參數	說明
     參數名稱	輸入介面名稱。
     參數類型	選擇介面型。
     介面地址	輸入傳遞參數的介面地址。
     參數描述	輸入參數描述。
     鑒權方式	選擇鑒權方式： 無：不進行鑒權。 密鑰：通過驗證密鑰進行鑒權，需要在下方輸入密鑰。
     是否關聯絡統參數	選擇關聯參數： 否：不關聯 是： 參數值設定（支援添加多個，最多添加20個）： 參數名稱：參數名稱必須為英文，支援輸入英文、數字、底線，且不可為空，長度不超過32個字元 顯示名稱：不超過32個字元 參數值： 下拉選項，支援選項：當前登入使用者資訊、目前使用者行級許可權 關聯參數選擇： 下拉透出可使用的系統參數
     是否關聯其他參數	選擇關聯參數： 否：不關聯 是： 參數值設定（支援添加多個，最多添加20個）： 參數名稱：參數名稱必須為英文，支援輸入英文、數字、底線，且不可為空，長度不超過32個字元 顯示名稱：不超過32個字元 參數值： 下拉選項，支援選項：關聯參數選擇 、手動輸入 關聯參數選擇 下拉全量透出參數管理下的參數 如介面型參數需要設定級聯關係，介面裡需包含參數之間級聯關係 手動輸入：選擇手動輸入時，支援手動輸入多個參數值 若需一個參數傳遞多個值，可以在一個參數值裡面填寫，多個值之間用三方約定的分隔字元分開，接收到後自己分隔

   • 常量型：

     

     

     參數	說明
     參數名稱	輸入介面名稱。
     參數類型	選擇常量型。
     參數描述	輸入參數描述。
     是否關聯其他參數	選擇關聯參數： 否：參數值設定（支援添加多個，最多添加20個） 參數值：至少配置一個模板參數，參數名稱必須為英文，且不可為空，長度不超過32個字元 顯示名稱：不超過32個字元 是：參數值及關聯參數設定（支援添加多個，最多添加20個）

4. 單擊確定，完成配置。

管理參數

參數列表提供以下操作按鈕：

• 詳情：單擊後可查看參數詳情。

• 編輯：單擊後可編輯參數，配置方法與建立時相同。

• 刪除：單擊後，在彈窗中確認刪除，即可刪除該參數。僅支援刪除當前未被使用的參數。

HTTP Endpoint Server

為了與Quick Audience的Webhook對接，您需要開發一個HTTP Server。Quick Audience將發起Post請求，請求逾時時間為10秒。Quick Audience發起的Post請求和接入方回執請求約定如下通用參數，為必傳項。

請求URL樣本：

{Webhook配置的url}?timestamp=1631865523&nonce=2e6eceb5737b473284c930c8ef79090e

鑒權方式

通過密鑰進行鑒權。Webhook配置時開啟鑒權，使用者填寫密鑰。

Quick Audience內部會根據使用者填寫的密鑰與URL請求參數timestamp和nonce進行HmacSHA256Hex簽名並產生signature，並將此signature通過Request Header傳遞過去來做鑒權。您的服務接受到請求後，同樣根據URL參數與Webhook通道配置的密鑰進行HmacSHA256Hex演算法加密。如果計算的值與從Request Header中傳過來的signature相同，則可以確定是此請求是從Quick Audience中發送的。上報回執時同理。

簽名演算法樣本：

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

/**
 * 簽名待處理的字串拼接
 */
public static String generateStr(String key, String timestamp, String nonce) {
    String[] array = new String[]{key, timestamp, nonce};
    StringBuilder sb = new StringBuilder();
    Arrays.sort(array);/* 字串排序*/
    for (int i = 0; i < 3; i++) {
        sb.append(array[i]);
    }
    return sb.toString();
}

Webhook Request

請求為Quick Audience向接入方發起的HTTP Post請求。Request Body是單使用者的觸發請求資訊，對於任何類型的資料（如整數、字串、文本變數等類型），在發送請求時，將所有的欄位全部轉為字串進行處理。

Post Body結構樣本（單個使用者，每批一般1~100個）：

[
    {
        "user_profile": {
            "target_type": "OPEN_ID",
            "target_id": "1917810",
            "customer_id": "客戶的唯一ID，如果上報事件需要使用這個ID"
        },
        "params": {
            "define_item1": "優惠券ID",
            "define_item2": "優惠券內容樣本，使用者所在的地址是北京"
        },
        "callback_params": {
            "webhook_id": "13312313",
            "send_time": "1625037472000",
            "nodeId": "節點Id",
            "instanceId": "執行個體Id",
            "batchId": "執行動作批次Id，可做批次等冪ID",
            "actionId": "執行動作執行個體Id，可做單條等冪ID",
            "customerId": "使用者Id，customerId"
        },
        "process_info": {
            "processInstanceId": "新版：旅程周期中，每個使用者的旅程執行個體ID",
            "processInstanceStartTime": "新版：旅程周期中，每個使用者的旅程執行個體開始時間，時間戳記格式",
            "processNodeInstanceId": "新版：旅程節點執行個體ID（每次不同）",
            "processNodeInstanceStartTime": "新版：旅程周期中，每個使用者的旅程的節點執行個體開始時間，時間戳記格式",
            "groupName":"nodeId:nodeName:groupResult(node.result),groupName(node.resultExt);nodeId:nodeName:groupResult(node.result),groupName(node.resultExt)",
            "@comment":{
              "groupName" : "節點id:節點名稱（介面配置的）:分組結果（隨機分組的百分比數字，兩位小數）:分組名稱（介面配置的）;多個用分號隔開"
            }
        }
    }
]

支援的ID類型：

接入方收到請求後，向Quick Audience返迴響應訊息。

響應體格式：

{
 "code":"OK",      //請求狀態代碼：返回OK代表請求成功，必須為大寫；返回其他為錯誤碼，接入方自訂。
  "message":"",    //狀態代碼描述，非必填。
}

回執上報

接入方執行營銷任務後，向Quick Audience上報回執，反饋營銷訊息的發送結果。

介面說明

WebHookCallBackMessage如下：

回執上報訊息樣本：

[
 {
 "msg_id": "業務側提供的唯一ID",
 "status": "回執狀態",
 "cst_id": "客戶ID，customerId",
 "send_time": "回執發送時間，時間戳記格式",
 "callback_params": {
 "參數原樣帶回": "將調用時的參數原樣帶回"
   }
 }
]

介面返回

請求樣本：

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 '[]'

響應樣本：

{
 "code": 200,
 "message": "成功"
}

Webhook參數、變數、常量、介面的區別是什嗎？

答：Webhook參數有多種類型，它們的區別和用法如下圖所示。

其中：

• 常量、介面是字元型（參數調用）參數賦值的兩種方式。

• 變數是文本型參數中插入的，可隨使用者而變的內容。