阿里云首页 智能用户增长

Webhook管理

管理员可以配置webhook,以便通过webhook对接您的一方系统(如CRM),实现在Quick Audience控制台通过一方系统向受众发送优惠券等。上述渠道称为自定义渠道,私有化营销、自动化营销模块均支持自定义渠道。

操作流程如下:

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

  2. 管理员新建webhook,对接一方系统,请参见新建webhook

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

  4. 管理员向需要使用webhook进行自定义渠道营销的用户同时授予以下两种权限:

    • 授予该webhook的使用权限,请参见授权

    • 通过创建含“用户营销-私有化营销-自定义营销渠道”权限的角色,授予自定义渠道的使用权限,请参见空间角色管理

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

新建webhook

操作步骤:

  1. 选择1111111>管理中心>工作空间>所在工作空间>Webhook管理,进入管理页面。1

  2. 单击右上角新建webhook

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

    参数

    说明

    webhook名称

    输入webhook名称。

    鉴权方式

    选择鉴权方式:

    • 无:不进行鉴权。

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

    请求地址

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

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

    发送ID类型

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

    支持当前受众的所有ID类型:OneID、UnionID、手机号码、电子邮箱、淘宝ID、淘宝昵称、支付宝ID、微博ID、手机IMEI、手机IDFA、手机IMSI、手机OAID、MAC地址、OpenID。

    webhook参数

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

    • 参数名称

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

    • 参数类型

    单击添加模版参数,可以增加一组webhook参数。

    是否开启回执设置

    选择是否开启回执设置,使一方系统能够通过上报回执将发送结果返回Quick Audience,显示在营销任务详情页面。

    若开启,您需要设置:

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

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

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

  4. 单击消息格式预览,下方将根据已配置的参数展示消息体格式。

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

测试发送

使用webhook进行自定义渠道营销前,您需要测试发送,确保其可用性。

说明

您也可以在创建营销任务时测试发送,请参见创建自定义渠道任务营销动作-自定义组件

操作步骤:

  1. 单击33图标。

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

    说明

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

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

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

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

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

授权

管理员以外的空间成员,若需要使用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接入开发包括以下几个方面,请参考我们给出的消息格式和样例进行开发。

HTTP Endpoint Server

为了与Quick Audience的webhook对接,您需要开发一个HTTP Server。注意是Post请求。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中发送的。上报回执时同理。

参数

含义

示例

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类型,target_type的value值表示ID类型,支持ID类型见下文,为大写;target_id的value值表示具体目标ID值。

params

Map<String,Object>

KV类型,具体KV为webhook配置时指定的。当文本类型中有变量时,变量值将直接填入params参数中,请参见下面的示例。

callback_params

Map<String,String>

为Quick Audience请求参数,需在上报回执时原样带回。

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

EMAIL

邮箱地址

MOBILE

手机号

TAOBAO_ID

淘宝ID

TAOBAO_NICK

淘宝昵称

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"
    }
}]