Version: 简体中文

Webhook

1.Webhook简介#

DM Hub 平台提供了各种 Open API 供外部系统调用，但在某些情况下，可能需要 DM Hub 在合适的时刻能够主动推送消息给外部系统，例如在自动流程执行到特定步骤时，能推送消息给客户的各种终端系统。

Webhook 功能就是 DM Hub 提供的消息推送机制，能够给在 DM Hub 平台上注册过的接口推送消息。

例：某客户在小程序中提交了一个订单，且订单中包含主推商品A，但是提交订单后20分钟未支付，此时可以发消息提醒客户完成支付，同时可以通过Webhook推送发券指令给到小程序，触发小程序主动灌券给该客户，触成交易的完成。（此例中小程序提交订单行为及商品信息等需要通过自定义事件、埋点等方式来打通数据，详情参考小程序埋点）

2.创建Webhook#

点击 【DM Hub】-【设置中心】-【Webhook】进入Webhook列表页，点击右上角的【新建】按钮创建新的Webhook。

img img

2.1参数说明#

  • 名称：给Webhook取一个有意义的名称，方便后续查看和更改。

  • 消息接收地址：Webhook消息的接收地址。该地址必须是合法的完整地址，包含使用的协议（如 http 或 https）。

  • 鉴权方式：为了防止非授信主体访问消息接收地址，消息接收地址的提供方需要提供一定的鉴权机制。DM Hub支持用以下鉴权机制来访问消息接收地址，具体内容参见 Webhook鉴权

    • 秘钥：DM Hub在发送消息的时候会使用该密钥对消息内容进行签名，消息接收地址在接收到消息时进行验签，从而保证消息来源以及消息内容没有被篡改过。
    • 基本认证: DM Hub发送消息时，使用HTTP基本认证访问消息接收地址。
    • OAuth2：DM Hub发送消息时，使用OAuth2的客户端凭证方式（client crendentials）访问消息接收地址。
    • 无：DM Hub发送消息时，不使用任何鉴权方式。

  • 触发类型

    • 自定义： 可在自动流程中作为一个动作组件，或手动圈选人群推送消息。选择此触发类型，需设置消息类型和消息体。

    • 事件订阅：指定事件发生后，该事件的内容会被发送给消息接收地址。DM Hub支持如下事件的订阅：客户事件、会员事件、客户属性变更、客户身份变更和营销活动属性变更。当订阅多个事件时，多个事件会分别逐条发送给消息接收地址，而不是一次性发送给消息接收地址。事件订阅的消息格式参见Webhook触发类型说明

  • 消息类型： 可选择以JSON或者文本格式发送消息。如果消息类型为JSON格式，则HTTP header中的Content-Type为application/json，如果为文本格式，则Content-Type为text/plain

  • 消息体：可自定义消息内容，并可选择插入内容变量。DM Hub支持的内容变量有：客户属性，会员属性，在用商品属性。如果是自动流触发的Webhook，还支持上下文事件属性。

  • 自动重试：如果推送失败，会自动进行重试。自动重试开启后，DM Hub会最多重试3次：分别为发送后的30分钟，60分钟和90分钟。

3.Webhook鉴权#

3.1秘钥#

对于设置了秘钥的 Webhook，DM Hub 向消息接收地址发送请求时，会使用秘钥生成消息内容的 hmac sha256 hex 摘要签名，携带在 header 的 X-Clab-Hmac-Signature 中。

在接收消息的代码中，使用相同的秘钥生成接收到的 payload 的 hmac sha256 hex 摘要签名，并与 header 中的签名进行比对，如果两者一致，则验签通过，表明消息来源可靠且消息内容没有被篡改过。

生成 hmac sha256 hex 摘要签名： 使用的 jar 包：

com.google.code.gson:gson:2.8.1
commons-codec:commons-codec:1.10

生成签名代码示例：

import com.google.gson.Gson
import com.google.gson.GsonBuilder
import org.apache.commons.codec.digest.HmacUtils
String sign(Map payload, String secret) {
Gson gson = new GsonBuilder().create();
String str = gson.toJson(payload);
return HmacUtils.hmacSha256Hex(secret, str.replaceAll("\\s+", ""));
}

3.2基本认证#

对于设置了基本身份认证的 Webhook， DM Hub向消息地址发送请求时，会在HTTP header中添加Authorization请求头。示例代码如下：

String content = username + ":" + password;
String token = "Basic " + Base64.getEncoder().encodeToString(content("utf-8"));
httpPost.setHeader("Authorization", token);

接收Webhook消息的服务可以用相同的方法验证请求的完整性。

3.3OAuth2#

对于设置了OAuth2认证的 Webhook， DM Hub首先会向token获取地址请求并获取access_token，然后携带access_token参数向消息接收地址发送消息。

3.3.1获取token的方式如下：#

GET https://{token获取地址}?appid={appid}&secret={secret}&grant_type=client_credentials

3.3.2发送消息时的参数名为access_token，如：#

POST https://{消息接收地址}?access_token={access_token}

3.4不使用任何鉴权方式#

如果Webhook鉴权设置无，则不做任何鉴权，直接访问接受消息地址

4.Webhook消息格式#

Webhook支持如下几类消息：自定义消息、客户事件、客户属性变更、客户身份变更和会员事件。下面分别对各种消息的格式一一做说明

4.1自定义消息#

自定义消息在手动发送、自动流程和提交表单时发送的Webhook中会使用。Webhook发送的消息格式会按照用户定义的格式发送，同时会替换里面的变量。

示例:

自定义JSON消息体:

{
"姓名":"${name!\"\"}",
"公司":"Convertlab"
}

Webhook消息接收地址接收到的消息内容:

{
"姓名": "DM Hub",
"公司": "Convertlab",
"MESSAGEID": "6f883839ec224526a1ecbb59ca8f5277"
}

JSON消息还会随消息携带一个MESSAGEID，用于方便定义问题。 自定义TEXT消息体:

${name!\"顾客\"}, 你好!

TEXT消息内容:

顾客, 你好!

自定义消息支持的变量 除了可以在界面中插入的变量，如客户变量，会员变量等。自定义消息还支持如下变量：

  • tenantId: 发送消息的租户ID
  • customerId: 对应的客户ID
  • campaign: 对应的营销活动编码
  • webhookId: 对应的Webhook Id
  • batchId: 该次发送的批次号（不一定有）

自动流发送的Webhook还可以使用如下变量:

  • flowId: 自动流程ID
  • flowVersion: 自动流程版本号
  • flowStep: 自动流程的步骤ID

4.2客户事件#

对于订阅了客户事件的Webhook，在客户事件发生时，DM Hub会将事件的内容发送给消息接收地址。Webhook可以订阅系统事件和自定义客户事件。当Webhook订阅了多个客户事件时，多条事件会依次发送给接收地址，而不是一次性发送多条。下面以点击微信菜单事件为例来说明消息的格式。

示例：

事件类型：点击微信菜单事件 事件关键字：click_menu 消息内容:

{
"MESSAGEID": "ce735894be7a4366a5ec905e2ec4b14c",
"topic": "customerEvent",
"data": {
"event": {
"createdDate": "2020-08-18T08:14:31.548Z",
"type": "created"
},
"object": {
"id": "784697835080734720",
"tenantId": 1,
"customerId": "577610832247089152",
"channelType": "wechat",
"channelAccount": "1234",
"event": "click_menu",
"targetId": "kdfb9nho734l6",
"targetName": "会员福利",
"date": "2020-08-18T08:14:29.285Z",
"userId": "okY_5jvvwjyrGzEFrHgSCIJ96GgY",
"identityType": "wechat",
"identityValue": "okY_xxxj_openid",
"lastUpdated": "2020-08-18T08:14:31.432Z"
}
}
}

字段说明:

字段说明
MESSAGEID本次发送的消息ID，用于调试
topic本次消息发送的类型，客户事件的topic都为customerEvent
datawebhook的消息内容
data.event事件的类型和发生的事件，对于客户事件Webhook消息，类型都是created
data.object客户事件的内容，具体参照客户事件

4.3客户属性变更#

对于订阅了客户属性变更的Webhook，在客户属性发生变更时，DM Hub会将发生变更的属性内容发送给消息接收地址。Webhook可以订阅系统事件和自定义客户事件。下面以客户公司属性发生变更为例来说明消息的格式。

示例：

消息内容:

{
"MESSAGEID": "ce735894be7a4366a5ec905e2ec4b14c",
"data": {
"event": {
"createdDate": "2020-08-18T08:14:31.548Z",
"type": "updated"
},
"object":{
"customerId": "577610832247089152",
"name": "张三",
"company": "百度",
"id": 1999
}
},
"topic": "customer"
}

字段说明:

字段说明
MESSAGEID本次发送的消息ID，用于调试
topic本次消息发送的类型，客户属性变更的topic都为customer
datawebhook的消息内容
data.event事件的类型和发生的事件，对于客户事件Webhook消息，类型可以是created,updated，deleted
data.object客户属性的内容，具体参照查询客户

4.4客户身份变更#

对于订阅了客户身份变更的Webhook，在系统客户发生增删改变更时，DM Hub会将事件的客户内容发送给消息接收地址。

示例：

消息内容:

{
"MESSAGEID": "ce735894be7a4366a5ec905e2ec4b14c",
"data": {
"event": {
"createdDate": "2020-08-18T08:14:31.548Z",
"type": "deleted"
},
"object":{
"id": 2850786358,
"version": 1,
"type": "wechat-unionid",
"value": "ombkt1FfCsqV91SQZ-p5-HfXqDVY",
"name": "小情绪",
"tenant_id": 4209,
"date_created": "2020-08-19 07:23:15",
"last_updated": "2020-08-19 07:23:15",
"customer_id": 785396805977360400
}
},
"topic": "customerIdentity"
}

字段说明:

字段说明
MESSAGEID本次发送的消息ID，用于调试
topic本次消息发送的类型，客户属性变更的topic都为customer
datawebhook的消息内容
data.event事件的类型和发生的事件，对于客户身份变更Webhook消息，类型可以是created，deleted
data.object客户身份相关信息
data.object.id事件ID
data.object.version版本号
data.object.type客户来源类型
data.object.value变更后的值
data.object.name姓名
data.object.tenant_idtenantId
data.object.date_created创建时间
data.object.last_updated更新时间
data.object.customer_id客户ID
data.object.value_md5value_md5

4.5会员事件#

对于订阅了会员事件的Webhook，在会员事件发生时，DM Hub会将事件的内容发送给消息接收地址。Webhook目前支持以下5种会员相关事件。

示例：

事件类型：会员等级升级事件 事件关键字：loyalty/membership_level_up 消息内容：

{
"MESSAGEID": "4e7eed8aceef464db0a60205808dd726",
"customerId": "785402304818944000",
"date": "2020-08-19T07:34:15Z",
"event": "loyalty/membership_level_up",
"membershipId": "119857345",
"newLevel": "LV1",
"newLevelId": 3441,
"oldLevel": "LV0",
"oldLevelId": 3433,
"tenantId": 306
}

字段说明:

字段说明
MESSAGEID本次发送的消息ID，用于调试
customerId客户ID
tenantIdtenantId
event事件关键字
membershipId会员 ID
date事件发生的时间
oldLevelId原等级 ID
newLevelId新等级 ID
oldLevel原等级名称
newLevel新等级名称

事件类型：会员等级降级事件 事件关键字：loyalty/membership_level_down 消息内容：

{
"MESSAGEID": "4e7eed8aceef464db0a60205808dd726",
"customerId": "785402304818944000",
"date": "2020-08-19T07:34:15Z",
"event": "loyalty/membership_level_down",
"membershipId": "119857345",
"newLevel": "LV1",
"newLevelId": 3446,
"oldLevel": "LV2",
"oldLevelId": 3434,
"tenantId": 306
}

字段说明:

字段说明
MESSAGEID本次发送的消息ID，用于调试
customerId客户ID
tenantIdtenantId
event事件关键字
membershipId会员 ID
date事件发生的时间
oldLevelId原等级 ID
newLevelId新等级 ID
oldLevel原等级名称
newLevel新等级名称

事件类型：系统发放优惠券事件 事件关键字：loyalty/loyalty_dispatch_coupon 消息内容：

{
"batchId": "flow-446065_6_false@@14",
"couponCode": "784637477225773056",
"couponId": "eoaQZWQ2mdPL7G3eRhm2",
"couponName": "【2020年8月】茶机300元优惠券",
"customerId": "778129594954950656",
"date": "2020-08-18T06:14:36Z",
"endDate": "2020-08-31T15:59:59Z",
"event": "loyalty/loyalty_dispatch_coupon",
"membershipId": "117743425",
"startDate": "2020-07-26T16:00:00Z",
"tenantId": 1209
}

字段说明:

字段说明
tenantIdtenantId
event事件关键字
membershipId会员 ID
date事件发生的时间
couponId优惠券 ID
couponName优惠券名称
batchId批次号
couponCode优惠券 code（该客户的唯一 code）
startDate起始有效日期
endDate截止有效日期

事件类型：领取优惠券事件 事件关键字：loyalty/membership_draw_coupon 消息内容：

{
"couponId": "0m_YTifBat76AfDCf0zX",
"couponName": "Chubbsafes集宝保柜100元优惠券",
"couponCode": "780350791910176800",
"startDate": "2020-08-11T16:00:00Z",
"endDate": "2020-09-10T15:59:59Z",
"customerId": null,
"membershipId": "117741857",
"event": "loyalty/membership_draw_coupon",
"tenantId": 1223,
"date": "2020-08-12T08:17:43Z"
}

字段说明:

字段说明
tenantIdtenantId
event事件关键字
membershipId会员 ID
date事件发生的时间
couponId优惠券 ID
couponName优惠券名称
couponCode优惠券 code（该客户的唯一 code）
startDate起始有效日期
endDate截止有效日期

事件类型：核销优惠券事件 事件关键字：loyalty/membership_redeem_coupon 消息内容：

{
"couponId": "eoaQZWQ2mdPL7G3eRhm2",
"couponName": "【2020年8月】茶机300元优惠券",
"couponCode": "782694747738224640",
"customerId": "782694697842884608",
"membershipId": "118793137",
"event": "loyalty/membership_redeem_coupon",
"tenantId": 1209,
"date": "2020-08-15T13:56:33Z"
}

字段说明:

字段说明
tenantIdtenantId
event事件关键字
membershipId会员 ID
date事件发生的时间
couponId优惠券 ID
couponName优惠券名称
couponCode优惠券 code（该客户的唯一 code）

5.消息发送#

5.1测试发送#

在针对群组进行群发Webhook之前，可选择某个用户来发送单条消息以进行测试

img

测试步骤：

  • 在Webhook列表中选择需要群发的Webhook，点击发送消息按钮。
  • 选择测试发送
  • 在输入框中输入客户姓名、微信昵称或者手机号码。

5.2群发#

Webhook创建完成后，如果该Webhook的触发类型为自定义触发，需要进行手动群发。

img

发送步骤：

  • 在Webhook列表中选择需要群发的Webhook，点击发送消息按钮。
  • 选择群发 在发送至群组的下拉列表中选择群组 选择发送时间. 如果选择定时发送则系统会在指定的时间开始发送Webhook消息。

5.3查看群发结果#

在webhook列表中可查看webhook发送的结果。

如果是测试消息，可查看到消息发送的详情，包括消息体、消息头以及服务器的响应结果 如果是群发的webhook消息，可以在发送列表页上看到该消息的发送状态：发送中、已完成等。

img

5.4接收自动流消息#

如下图所示，在创建自动流程时，可以添加 Webhook 动作节点，用以将相关的上下文信息通过 Webhook 推送给外部系统。

img img

5.5接收表单提交相关消息#

如下图所示，在表单中，可以设置提交表单后触发 Webhook，用以将相关的上下文信息通过 Webhook 推送给外部系统。

img img img

5.6发送记录#

给客户发送webhook后系统会在客户时间轴记录“系统发送Webhook消息”事件，并在事件属性中记录Whbhook ID、Whbhook 名称。

img