通过webhook对接其他渠道

优质

小牛编辑

134浏览

2023-12-01

通过诸葛io智能触达的webhook配置，可以让您自定义营销行为。Webhook是一个HTTP形式的回调接口，该接口需要您的研发团队按照下文提供实现。

当智能触达检测到用户满足设置的行为条件时，会去回调请求该接口，并把该用户的基本信息以json格式的请求体传递给您的服务器，您可以在接口中利用这些信息做任何想做的事情，比如给用户发送短信、推送、邮件、红包，记录用户的行为或进行一些复杂的业务计算。

一、配置和管理webhook触达渠道

1. 配置webhook渠道

在诸葛「智能触达→设置→触达渠道→Webhook」中，点击「新建渠道」（或编辑已有的渠道），开始配置webhook渠道：

输入渠道名称，应尽量使用业务人员容易理解的渠道名称，比如「××平台站内信」或「××短信」等；
输入回调的接口URL地址，参考接口和数据格式；
输入用于确认调用身份的Secret Key；
添加模板化参数，模板化参数可以帮助营销和运营人员解决触达内容内容输入等问题，详见模板化参数；
点击「确定」完成创建。

2. Webhook渠道的类型

为了方便营销和运营人员使用，智能触达中对触达用户的渠道进行了分类组织（目前支持推送「消息、短信、其它」三种类型）。

在创建和管理webhook渠道时，可以为渠道设置合适的分类。比如将「xx短信」渠道的类型设置为「短信」。

3. 模板化参数的作用

营销和运营人员在创建使用webhook渠道的触达活动时，很可能需要同时为该活动撰写和配置诸如触达的标题、内容等。

为了让营销和运营人员使用起来更加方便，我们可以让您在创建webhook渠道时，通过定义「模板化参数」的方式，在智能触达平台中为营销和运营人员提供上述内容的编辑界面。

目前平台支持四种类型的参数化模板：字符串（短文本）、长文本、日期、数值。编辑界面分别如下图：

二、接口和数据格式

1. 请求方法

目前只支持POST形式的请求。

2. 请求头

Content-Type: application/json; charset=utf-8
User-Agent: ZhugeIO-Webhook/1.0
X-ZhugeIO-ReqID: 55f168b8-5626-11e7-8ef6-6c40088b9060
X-ZhugeIO-HookType: marketing_cloud_activity
X-ZhugeIO-DataType: single
X-ZhugeIO-Sign: 86404d5810f4e248a887d1c0248b36cb87aa641a

需要说明的是X-ZhugeIO-ReqID字段，该字段为每个请求提供了一个唯一ID进行标识，您的开发人员以及诸葛的技术人员都可以通过该字段来定位到每一次请求进行排错。

另外需要注意X-ZhugeIO-Sign字段，该字段提供了一种安全验证方式，可以用于防范请求伪造。默认该字段是没有的，如果需要安全验证，您需要向诸葛的技术支持人员提供一个Secrect Key，系统在发送webhook请求的时候会以该Secrect Key结合其它请求字段来计算出X-ZhugeIO-Sign，在webhook的实现逻辑中需要通过同样的算法计算出该Sign，对比两者是否一致即可。

3. 请求体

{
    "activity": {
        "activity_id": 10010,
        "activity_name": "注册送十元优惠券活动",
        "activity_type": "event",
        "activity_send_type": "push"
    },
    "user_properties": {
        "手机号": "17600817832",
        "邮箱": "chihongze@zhugeio.com",
        ...
    },
    "trigger_event": {
        "$eid": "提交订单",
        "_下单金额": "50.00"
        ...
    },
    "params": {
        "title": "双十一促销来啦！",
        "content": "xx商城双十一，秒杀打折促销……"
    },
    "push_info": {
        "platform": "and",
        "push_id": "xxxx-xxxx-xxxx"
    }
}

请求体分为了五个部分，其中：

activity是活动相关的信息，当您多个活动使用同一个Webhook但不同的活动又有一些业务逻辑差别的时候可以使用该部分数据做区分；
user_properties是用户属性，就是您在SDK中上传的用户属性；
trigger_event是触发事件的属性，其中以'$'开头都是内置属性，以'_'开头的都是自定义属性，内置属性通常只需要关注$eid即可，即事件名称，只有触发类和转化类活动才会推送trigger_event，而手动活动没有该字段；
params是您定义的模板化参数的值，详见模板化参数；
push_info仅当webhook渠道类型为推送时（此时activity.activity_send_type取值为push）才出现，传递的内容为客户端的平台类型（and/ios）和用户的pushid。

开发者需要注意的是，匿名用户现在也会被推送用户属性，匿名用户的user_properties中目前只有zg_id一个字段，在取用属性时需要先判断一下属性是否存在或者是否为空，以避免发生空指针之类的错误。

4. 返回结果

智能触达根据Webhook接口返回的HTTP状态码来判断成功失败，如果返回的状态码是2xx，那么就会认为执行成功，同时发送成功计数会+1，如果是其它的状态码，那么会认为执行失败，发送计数不会增加。

三、注意事项

1. 超时

如果您的Webhook接口响应特别的缓慢，那么智能触达不会一直等待下去，默认等待超时时间是10秒。超时会按照发送失败来处理。

建议您不要在Webhook中进行耗时的计算，而是进行简单处理后立即返回，如果确实需要进行很耗时的计算，那么可以将Webhook中接收到的数据封装成事件，发布到消息队列中，在后台的Worker中进行计算。

2. 安全

建议对Webhook的访问提供限制，只在智能触达被部署的内网可访问。

3. 调试和问题排查

在第一次对接时，不要马上就执行真实的业务逻辑，尤其是发送类的业务，建议先使用一个空的Webhook，只把接受到的参数打印出来，人工观察数据没有问题以及请求压力可接受后，再对接正式的业务。

另外建议将收到的请求数据和唯一请求ID记录日志，方便问题的排查。如果无法排查，请及时联系我们的技术支持人员。

四、适用场景举例

场景1 智能触达内建的推送&短信渠道不能满足需求

诸葛内置的推送&短信渠道有限，可能暂不包含您使用的渠道，或者您的公司已经拥有了一套统一的消息中心。那么这种情况下就可以编写一个webhook进行中转，在智能触达与您自己的渠道之间做一个适配。

场景2 拥有复杂的内容生成逻辑

虽然智能触达允许您在发送内容中动态指定用户属性，但有些时候我们需要根据逻辑判断来生成发送的内容。比如用户触发了“提交订单”事件，事件中包含了“下单金额”的事件属性，您想通过该属性来生成不同的发送内容，比如满100元的送10元优惠券，满200元的送20元优惠券。那么就可以在webhook中结合trigger_event进行判断后生成发送内容。

五、Demo

进入 Java版Demo