Webhook管理
管理员可以配置webhook,以便通过webhook对接您的一方系统(如CRM),实现在Quick Audience控制台通过一方系统向受众发送优惠券等。私有化营销、自动化营销模块均支持webhook营销。
操作流程如下:
针对您的一方系统完成webhook接入开发,请参见webhook接入文档。
管理员新建webhook,对接一方系统,请参见新建webhook。
管理员测试发送,确保能发送成功,请参见测试发送。
管理员向需要使用webhook进行营销的用户同时授予以下两种权限:
管理员、已授权用户在私有化营销模块创建webhook任务,或在自动化营销模块配置webhook组件,调用一方系统向受众进行营销,具体操作,请分别参见创建webhook任务、营销动作-webhook组件。
新建webhook
操作步骤:
选择
>管理中心>工作空间>所在工作空间>Webhook管理,进入管理页面。
单击右上角新建webhook。
在弹窗中配置参数,如下表所示。
参数
说明
webhook名称
输入webhook名称。
鉴权方式
选择鉴权方式:
无:不进行鉴权。
密钥:通过验证密钥进行鉴权,需要在下方输入密钥。
请求地址
输入要接收消息推送的接口地址,必须是以http或https开头的完整地址。
建议使用HTTPS协议,以提高信息传输的安全性。
发送ID类型
选择允许发送的ID类型,可多选。但在创建任务时,每个任务仅可选择发送一种ID。
支持选择当前受众可用的所有ID类型。
webhook参数
您可以定义webhook参数,在使用该webhook创建不同的营销任务时,可以灵活定义这些参数的值。例如:一方系统设置的发送内容为“在{address}进行折扣活动”,{address}}即为一个参数,在创建营销任务时,需要指定为具体内容。
参数名称
显示名称:显示在营销任务创建页面上的参数名称。
参数类型:参数的数据类型,支持字符型、数值型、文本型、日期型。
单击添加模版参数,可以增加一组webhook参数。
是否开启回执设置
选择是否开启回执设置,使一方系统能够通过上报回执将发送结果返回Quick Audience,显示在营销任务详情页面,或用于自动化营销的结果多分支组件。
若开启,您需要设置:
数据回收周期:超过该周期后,Quick Audience将不再接收发送结果。
状态code、状态值:回执中,状态code为发送结果代码,如:200;状态值为对应的发送结果,如:成功。
状态code、状态值可能有多对,单击新增状态,可以增加一对。
单击消息格式预览,下方将根据已配置的参数展示HTTP Post请求的消息体格式。详细说明,请参见webhook接入文档。
单击确定,完成配置。
测试发送
使用webhook进行营销前,您需要测试发送,确保其可用性。
您也可以在创建营销任务时测试发送,请参见创建webhook任务、营销动作-webhook。
操作步骤:
单击
图标。
在弹窗中选择要测试发送的ID类型,输入测试ID、webhook参数值。
说明一次仅能测试一种ID类型。测试营销任务需要发送的ID类型即可。
单击确定,系统将通过webhook调用一方系统向测试ID发送消息。
弹窗将显示测试发送是否成功。
测试发送成功:请检查一方系统是否收到了webhook请求,测试ID是否收到消息。若未收到,请单击弹窗中的下载日志,排查原因。
测试发送失败:请单击弹窗中的下载日志,排查原因。
授权
管理员以外的空间成员,若需要使用webhook创建营销任务,必须先由管理员授予该webhook的使用权限,并加入带有“用户营销-私有化营销-webhook”权限的自定义角色。
授权操作步骤:
单击
>授权,进入授权页面,如下图所示。
选择授权方式:支持按用户和按用户组。
说明两种授权方式相互排斥,仅可选其中一种进行授权。若已按一种方式授权,再次授权时选择另一种方式,则使用旧授权方式的授权将解除,仅生效使用新授权方式的授权。
下方显示已授权用户账号/用户组,以及授权有效期。
解除授权:单击账号/用户组对应的移除,即可解除对该账号/用户组的授权,立即生效。
授权:选择要授权的账号/用户组,可多选,设置有效期,单击确定完成授权。
关闭/开启
webhook创建后,默认为开启状态,此时可测试、使用webhook;若需要编辑、删除webhook,必须先关闭webhook。
通过右侧的开关,您可以关闭、开启
webhook。
编辑
在关闭webhook后,您可以对其进行编辑。
单击图标,进入编辑界面,后续操作与创建时相同。
不支持编辑开启状态的webhook,请先关闭。
若编辑前已开启回执设置,则不支持修改或删除已配置的状态code、状态值。
复制
单击>复制,进入新的配置页面,已默认填写与原webhook相同的配置项,支持修改,单击确定完成复制。
复制生成的新webhook,默认为关闭状态,需要手动开启,才能测试、使用。
删除
在关闭webhook后,若该webhook未被用于任何营销任务,您可以删除该webhook。
单击>删除,确认后即删除该webhook。
webhook接入文档
webhook接入开发包括以下几个方面,请参考我们给出的消息格式和样例进行开发。
HTTP Endpoint Server
为了与Quick Audience的webhook对接,您需要开发一个HTTP Server。注意是Post请求,请求超时时间为10秒。Quick Audience发起的webhook请求和接入方回执请求约定如下通用参数,为必传项。
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中发送的。上报回执时同理。
参数 | Header | 示例 |
---|---|---|
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等信息,需在上报回执时原样带回。 |
Post Body结构示例:
[{
"user_profile":{
"target_type":"OPEN_ID",
"target_id":"1917810"
},
"params":{
"define_item1":"优惠券ID",
"define_item2":"优惠券内容示例,用户所在的地址是北京" //北京是变量${city}填入的变量值
},
"callback_params":{
"task_id":"1234455sseeddedd1234455sseeddedd",
"webhook_id":"13312313",
"send_time":"1625037472000"
}
}]
支持的ID类型:
ID类型 | 含义 |
---|---|
ONEID | OneID |
邮箱地址 | |
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返回响应消息。
响应体格式:
{
"code":"OK", //请求状态码:返回OK代表请求成功,必须为大写;返回其他为错误码,接入方自定义。
"message":"", //状态码描述,非必填。
"requestId":"" //请求ID,接入方自定义。
}
回执上报
接入方执行营销任务后,向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.target_id。 |
send_time | String | 毫秒级时间戳。 |
callback_params | Map<String,String> | webhook请求时携带的callback_params。 |
回执消息示例:
[{
"msg_id":"236eceb5737b473284c930c8ef79090e",
"status":"200",
"cst_id":"1917810",
"send_time":"1625037473000"
"callback_params":{
"task_id":"2e6eceb5737b473284c930c8ef79090e",
"webhook_id":"13312313",
"send_time":"1625037472000"
}
}]