Webhook管理

创建参数

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参数有多种类型，它们的区别和用法如下图所示。

其中：

• 常量、接口是字符型（参数调用）参数赋值的两种方式。

• 变量是文本型参数中插入的，可随用户而变的内容。