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中发送的。上报回执时同理。

签名算法示例：

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上报回执，反馈营销消息的发送结果。

接口调通说明参照：Quick Audience开放平台API

接口说明

WebHookCallBackMessage如下：

WebHookCallBackResult如下：

OemImportTaskInfoResponse如下：

请求示例

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"

响应示例：

• {

  "data": {

  "code": 200,

  "message": "成功"

  },

  "errorCode": null,

  "errorDesc": null,

  "exStack": null,

  "opers": [],

  "solution": null,

  "success": true,

  "traceId": "0ada03af17183523948084322d00b4"

  }

Webhook参数、变量、常量、接口的区别是什么？

答：Webhook参数有多种类型，它们的区别和用法如下图所示。

其中：

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

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