創建參數

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

   

2. 單擊右上角新建Webhook參數。

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

   • 接口型：

     

     參數	說明
     參數名稱	輸入接口名稱。
     參數類型	選擇接口型。
     接口地址	輸入傳遞參數的接口地址。
     參數描述	輸入參數描述。
     鑒權方式	選擇鑒權方式： 無：不進行鑒權。 密鑰：通過驗證密鑰進行鑒權，需要在下方輸入密鑰。
     是否關聯其他參數	選擇關聯參數： 否：不關聯 是： 參數值設置（支持添加多個，最多添加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中發送的。上報回執時同理。

簽名算法示例：

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};
    StringBuffer sb = new StringBuffer();
    // 字符串排序
    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 Header信息：

Header信息讀取后需要通過java.net.URLDecoder#decode(java.lang.String, java.lang.String)解碼，編碼方式為UTF-8。可能包含以下信息：

processId=自動化營銷活動ID
processName=自動化營銷活動名稱
processSchedulerId=自動化營銷活動每次周期調度的ID
processSchedulerName=自動化營銷活動每次周期調度的名稱：自動化營銷活動ID+周期的時間拼接字符串
processSchedulerStartTime=自動化營銷活動周期開始時間，時間戳格式
processNodeId=自動化營銷活動節點ID（每個周期的節點ID都是一樣的）
processNodeName=自動化營銷活動節點名稱（每個周期的節點ID都是一樣的）
activityId=關聯子活動的主活動ID
activityName=關聯子活動的主活動名稱
subActivityId=關聯子活動ID
subActivityName=關聯子活動名稱

jobId=廢棄：等于processId，推薦用processId
jobName=廢棄：等于processName，推薦用processName
nodeId=廢棄：等于processNodeId，推薦用processNodeId
nodeName=廢棄：等于processNodeName，推薦用processNodeName
taskStartTimestamp=廢棄：等于processSchedulerStartTime，是時間戳格式，推薦用processSchedulerStartTime
processInstanceId=廢棄：兼容老版本：等于processSchedulerId
processInstanceName=廢棄：兼容老版本：等于processSchedulerName
processInstanceStartTime=廢棄：兼容老版本：等于processSchedulerStartTime

taskId=無此字段，等于processNodeInstanceId，無法兼容
processNodeInstanceId=無此字段，無法兼容
processNodeInstanceStartTime=無此字段，無法兼容
nodeStartTimestamp=無此字段，等于processNodeInstanceStartTime，無法兼容

Post Body結構示例（單個用戶示例，每批一般1~100個用戶）：

[
    {
        "user_profile": {
            "target_type": "OPEN_ID",
            "target_id": "1917810",
            "customer_id": "用戶的唯一ID，如果上報事件需要使用這個ID"
        },
        "params": {
            "define_item1": "優惠券ID",
            "define_item2": "優惠券內容示例，用戶所在的地址是北京" //北京是變量${city}填入的變量值
        },
        "callback_params": {
            "task_id": "廢棄",
            "Webhook_id": "13312313",
            "send_time": "1625037472000",
            "nodeId": "節點Id",
            "instanceId": "實例Id",
            "actionId": "執行動作實例Id",
            "customerId": "用戶Id，customerId",
        },
        "process_info": {
            "processInstanceId": "新版：自動化營銷活動周期中，每個用戶的自動化營銷活動實例ID",
            "processInstanceStartTime": "新版：自動化營銷活動周期中，每個用戶的自動化營銷活動實例開始時間，時間戳格式",
            "processNodeInstanceId": "新版：自動化營銷活動節點實例ID（每次不同）",
            "processNodeInstanceStartTime": "新版：自動化營銷活動周期中，每個用戶的自動化營銷活動的節點實例開始時間，時間戳格式",
            "groupId":"新版：分組ID",
            "groupName":"新版：分組名稱"
        }
    }
]

Quick Audience空間支持的用戶ID類型包括本空間的ID類型管理頁面中所有已啟用狀態的ID，請在代碼中使用ID類型編碼代表對應的ID。

• 系統預置ID的ID類型編碼，請查閱系統預置ID列表。

• 自定義ID的ID類型編碼，請單擊列表中自定義ID的編輯按鈕，查看ID類型編碼。

接入方收到請求后，向Quick Audience返回響應消息。

響應體格式：

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

回執上報

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

HTTP請求URL：

http://${region域名}/restapi/marketing2/webhook/receiveWebHookCallBack?timestamp=1631865523&nonce=2e6eceb5737b473284c930c8ef79090e

Post Body：為List，多個用戶的回執信息合并在一起。

回執消息示例：

[
    //每個用戶一個，一次可上報多個，最好100個以內
    {
        "status": "回執狀態",
        "cst_id": "客戶ID，customerId",
        "send_time": "回執發送時間，時間戳格式",
        "callback_params": {
            "參數原樣帶回": "將調用時的參數原樣帶回"
        }
    }
]

回執返回結果：

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

  • 全部失敗：{"code":99999, "message":"每一條的錯誤信息json格式"}

  • 部分失敗：{"code":99998, "message":"每一條的錯誤信息json格式"}

Webhook參數、變量、常量、接口的區別是什么？

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

其中：

• 常量、接口是字符型（參數調用）參數賦值的兩種方式。

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