Webhook管理

管理员可以配置Webhook,以便通过Webhook对接您的一方系统(如CRM)或三方系统,实现在Quick Audience控制台向受众发送优惠券等。触达营销、自动化营销模块均支持Webhook。

操作流程如下:

  1. 针对您的一方系统或三方系统完成Webhook接入开发,请参见Webhook接入文档

  2. 若Webhook参数需要使用字符型参数调用的方式,包括采用常量或通过接口传参,管理员需要在新建Webhook前配置参数,请参见参数管理

  3. 管理员新建Webhook,对接一方系统或三方系统,请参见新建Webhook

  4. 管理员测试发送,确保能发送成功,请参见测试发送

  5. 管理员向需要使用Webhook的非管理员授予Webhook的使用权限,请参见授权

  6. 管理员、已授权用户在触达营销模块创建Webhook任务,或在自动化营销模块配置Webhook组件,调用一方系统或三方系统向受众进行营销,具体操作,请分别参见创建Webhook任务营销动作-Webhook组件

新建Webhook

操作步骤:

  1. 选择工作空间>配置管理>营销配置>Webhook管理,进入Webhook列表。image

  2. 单击右上角新建Webhook

  3. 在弹窗中配置参数,如下表所示。p440999

    参数

    说明

    Webhook名称

    输入Webhook名称。

    鉴权方式

    选择鉴权方式:

    • 无:不进行鉴权。

    • 密钥:通过验证密钥进行鉴权,需要在下方输入密钥。

    请求地址

    输入要接收消息推送的接口地址,必须是以http或https开头的完整地址。

    建议使用HTTPS协议,以提高信息传输的安全性。

    发送ID类型

    选择允许发送的ID类型,可多选。但在创建任务时,每个任务仅可选择发送一种ID。

    支持选择当前受众可用的所有ID类型。

    Webhook参数

    您可以定义Webhook参数,在使用该Webhook创建不同的营销任务时,可以灵活定义这些参数的值。例如:一方系统或三方系统设置的发送内容为“在{address}进行折扣活动”,{address}即为一个参数,在创建营销任务时,需要指定为具体内容。

    • 参数名称

    • 显示名称:显示在营销任务创建页面上的参数名称。

    • 参数类型:参数的数据类型,支持字符型、数值型、文本型、日期型、字符型(参数调用)。

      • 对于字符型(参数调用),需要选择参数使用的常量或接口,常量或接口需要事先配置,请参见参数管理

    单击添加模板参数,可以增加一个Webhook参数。

    是否开启回执设置

    选择是否开启回执设置,使一方系统或三方系统能够通过上报回执将发送结果返回本空间的分析源,显示在营销任务详情页面,或用于自动化营销的结果多分支组件。

    若开启,您需要设置:

    • 数据回收周期:超过该周期后,Quick Audience将不再接收发送结果。

    • 状态code、状态值:回执中,状态code为发送结果代码,如:200;状态值为对应的发送结果,如:成功。

      状态code、状态值可以有多对,单击新增状态,可以增加一对。

  4. 单击消息格式预览,下方将根据已配置的参数展示HTTP Post请求的消息体格式。详细说明,请参见Webhook接入文档

  5. 单击确定,完成配置。

测试发送

使用Webhook进行营销前,您需要测试发送,确保其可用性。

说明

您也可以在创建营销任务时测试发送,请参见创建Webhook任务营销动作-Webhook

操作步骤:

  1. 单击33图标。

  2. 在弹窗中选择要测试发送的ID类型,输入测试ID、Webhook参数值。

    说明

    一次仅能测试一种ID类型。测试营销任务需要发送的ID类型即可。

    2645
  3. 单击确定,系统将通过Webhook调用一方系统或三方系统向测试ID发送消息。

    弹窗将显示测试发送是否成功。

    • 测试发送成功:请检查一方系统或三方系统是否收到了Webhook请求,测试ID是否收到消息。若未收到,请单击弹窗中的下载日志,排查原因。

    • 测试发送失败:请单击弹窗中的下载日志,排查原因。

    同时,最近一次的测试发送信息也将显示在Webhook列表,如下图所示。

    562

授权

管理员以外的空间成员,若需要使用Webhook创建营销任务,必须加入含“用户营销-触达营销-Webhook”权限的角色,并由管理员授予该Webhook的使用权限。

授权操作步骤:

  1. 单击43>授权,进入授权页面,如下图所示。323544

  2. 选择授权方式:支持按用户按用户组

    说明

    两种授权方式相互排斥,仅可选其中一种进行授权。若已按一种方式授权,再次授权时选择另一种方式,则使用旧授权方式的授权将解除,仅生效使用新授权方式的授权。

    下方显示已授权用户账号/用户组,以及授权有效期。

  3. 解除授权:单击账号/用户组对应的移除,即可解除对该账号/用户组的授权,立即生效。

  4. 授权:选择要授权的账号/用户组,可多选,设置有效期,单击确定完成授权。

关闭/开启

Webhook创建后,默认为开启状态,此时可测试、使用Webhook;若需要编辑、删除Webhook,必须先关闭Webhook。

通过右侧的开关,您可以关闭关、开启开Webhook。

编辑

在关闭Webhook后,您可以对其进行编辑。

单击编辑图标,进入编辑界面,后续操作与创建时相同。

说明
  • 不支持编辑开启状态的Webhook,请先关闭。

  • 若编辑前已开启回执设置,则不支持修改或删除已配置的状态code、状态值。

复制

单击43>复制,进入新的配置页面,已默认填写与原Webhook相同的配置项,支持修改,单击确定完成复制。

复制生成的新Webhook,默认为关闭状态,需要手动开启,才能测试、使用。

删除

在关闭Webhook后,若该Webhook未被用于任何营销任务,您可以删除该Webhook。

单击43>删除,确认后即删除该Webhook。

参数管理

若Webhook参数需要使用字符型参数调用的方式,包括采用常量或通过接口传参,管理员需要在新建Webhook前配置参数。

  • 接口型:通过接口传递参数值。在创建Webhook任务时,Quick Audience将读取接口内的所有参数值,供创建时选择。

    接口开发规范,请参见Webhook接口参数接入文档

  • 常量型:参数值固定。可以设置多个固定参数值,供创建Webhook任务时选择。

创建参数

  1. 选择工作空间>配置管理>营销配置>Webhook管理>Webhook参数管理,进入Webhook参数列表。

    image
  2. 单击右上角新建Webhook参数

  3. 在弹窗中配置参数,常量型、接口型参数的配置方法不同:

    • 接口型:

      1

      参数

      说明

      参数名称

      输入接口名称。

      参数类型

      选择接口型

      接口地址

      输入传递参数的接口地址。

      参数描述

      输入参数描述。

      鉴权方式

      选择鉴权方式:

      • 无:不进行鉴权。

      • 密钥:通过验证密钥进行鉴权,需要在下方输入密钥。

    • 常量型:

      2

      参数

      说明

      参数名称

      输入接口名称。

      参数类型

      选择常量型

      参数描述

      输入参数描述。

      参数设置

      输入参数值和对应的显示名称。在创建Webhook任务,选择常量型参数要发送的内容时,可选项将展示为显示名称。

      单击添加参数,可以增加一个参数。

  4. 单击确定,完成配置。

管理参数

参数列表提供以下操作按钮:

  • 详情:单击后可查看参数详情。

  • 编辑:单击后可编辑参数,配置方法与创建时相同。

  • 删除:单击后,在弹窗中确认删除,即可删除该参数。仅支持删除当前未被使用的参数。

Webhook接入文档

Webhook接入开发包括以下几个方面,请参考我们给出的消息格式和样例进行开发。

HTTP Endpoint Server

为了与Quick Audience的Webhook对接,您需要开发一个HTTP Server。Quick Audience将发起Post请求,请求超时时间为10秒。Quick Audience发起的Post请求和接入方回执请求约定如下通用参数,为必传项。

URL参数

含义

示例

timestamp

秒级时间戳

1631865523

nonce

32位随机字符串

2e6eceb5737b473284c930c8ef79090e

请求URL示例:

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

Header

含义

说明

X-QA-Hmac-Signature

鉴权签名

开启鉴权时使用,鉴权方式见下文。

未开启鉴权时,该Header填空字符串""。

鉴权方式

通过密钥进行鉴权。Webhook配置时开启鉴权,用户填写密钥。

Quick Audience内部会根据用户填写的密钥与URL请求参数timestamp和nonce进行HmacSHA256Hex签名并生成signature,并将此signature通过Request Header传递过去来做鉴权。您的服务接受到请求后,同样根据URL参数与Webhook通道配置的密钥进行HmacSHA256Hex算法加密。如果计算的值与从Request Header中传过来的signature相同,则可以确定是此请求是从Quick Audience中发送的。上报回执时同理。

参数

含义

示例

key

Webhook配置的密钥

123456789

签名算法示例:

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是单用户的触发请求信息。

字段名

字段类型

说明

user_profile

Map<String,String>

KV类型,传递用户ID。

target_type的value值表示ID类型,支持ID类型见下文,为大写;target_id的value值表示具体目标ID值。

params

Map<String,Object>

KV类型,传递Webhook配置时指定的参数。

对于任何类型的参数(含参数调用),在发送请求时,将所有的参数字段全部转为字符串进行处理。

当文本类型中有变量时,变量值将直接填入params参数中,请参见下面的示例。

callback_params

Map<String,String>

为Quick Audience请求参数,包含任务ID、组件ID等信息,需在上报回执时原样带回。

process_info

Map<String,String>

流程信息中的部分实例信息,因为这些信息对于不同的用户会不同。

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":"新版:分组名称"
        }
    }
]

支持的用户ID类型:

用户ID类型

含义

ONEID

OneID

EMAIL

邮箱地址

MOBILE

手机号

TAOBAO_ID

淘宝ID

TAOBAO_NICK

淘宝昵称

OUID

淘宝OUID

IMEI

手机IMEI

IMSI

手机IMSI

IDFA

手机IDFA

MAC_ORG

MAC地址

WEIBO_ID_ORG

微博ID

ALIPAY_ID

支付宝ID

UNION_ID

微信UnionID

OAID

OAID

OPEN_ID

微信OpenID

说明

Quick Audience储存的ID加密方式支持原文/AES/MD5/SHA256,向一方系统或三方系统发送ID前会对已AES加密的ID进行解密,因此Quick Audience向一方系统或三方系统发送的ID加密方式可能是原文/MD5/SHA256,一方系统或三方系统可以根据ID实际使用到的加密方式决定是否支持MD5/SHA256解密。

接入方收到请求后,向Quick Audience返回响应消息。

响应体格式:

{
 "code":"OK",      //请求状态码:返回OK代表请求成功,必须为大写;返回其他为错误码,接入方自定义。
  "message":"",    //状态码描述,非必填。
}

回执上报

接入方执行营销任务后,向Quick Audience上报回执,反馈营销消息的发送结果。

HTTP请求URL:

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

Post Body:为List,多个用户的回执信息合并在一起。

字段

类型

说明

msg_id

String

32位消息唯一ID,由接入方生成。

status

String

结果状态,即Webhook配置中定义的状态code,如200。

cst_id

String

触达的用户ID,为user_profile.customer_id。

send_time

String

毫秒级时间戳。

callback_params

Map<String,String>

Webhook请求时携带的callback_params,原样带回即可。

回执消息示例:

[
    {
        "msg_id": "业务侧提供的唯一ID",
        "status": "回执状态",
        "cst_id": "客户ID,customerId",
        "send_time": "回执发送时间,时间戳格式",
        "callback_params": {
            "参数原样带回": "将调用时的参数原样带回"
        }
    }
]

回执返回结果:

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

  • 全部失败:{"code":99999, "message":"每一条的错误信息,json格式"}

  • 部分失败:{"code":99998, "message":"每一条的错误信息,json格式"}

FAQ

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

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

其中:

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

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

阿里云首页 智能用户增长 相关技术圈