功能概述

  • Webhook 是一个 HTTP 形式的回调接口，用以支持自定义的营销行为，该接口需要研发团队一些开发工作，详见 Webhook 对接文档。
  • 当用户被触发（满足计划中的条件）时，会去回调请求 Webhook 接口，并把该用户的基本信息或其他自定义内容以 json 格式的请求体传递给客户的服务器，客户就可以在接口中利用这些信息进行后续的操作，比如，对用户进行消息推送、权益发放等。

适用场景

  • 客户已经拥有了一套消息推送平台，那么这种情况下就可以编写一个 Webhook 进行中转，在智能运营与已对接的推送通道之间做一个适配。

  • 对接权益系统，利用神策智能运营灵活的规则定义来触发优惠券、积分的发放（受众筛选规则、行为触发规则）。

创建 Webhook

在 Webhook 通道管理列表中，点击创建 Webhook，进入创建页面。

输入请求地址

输入 Webhook 要请求的目标地址，支持 http、https。

选择发送 ID

选择发送 ID 在用户表里存储的属性字段，如，通过 Webhook 对接站内信，那发送 ID 这里选择登陆 ID。注意，创建计划进行预估受众时，会过滤掉发送 ID 为空的用户。Webhook 类型的计划里的计划触发、目标完成指标也都会过滤掉发送 ID 为空的用户。

选择是否添加回执

添加回执需要客户上报回执事件。添加成功后，当 Webhook 触达用户时，将回传触达结果（发送成功/发送失败），并展示在运营计划/流程画布的数据分析中。

添加用户属性

可添加多条用户属性，配置成功之后，运营人员在创建计划时不需要定义这部分的内容，配置好的用户属性会自动加到请求体里。

  • 参数名称：自定义发送的用户属性参数的名称，必须为英文，为请求里的 Key。

  • 属性参数：选择要发送的用户属性。

  • 默认值：当属性值为空时使用默认值。

添加模板参数

可添加多个模板参数，配置成功之后，运营人员在创建计划时可以灵活定义这些模板参数的值，比如配置了模板参数标题、内容，那么后续每次创建计划时就可以灵活定义发送的标题和内容。

  • 参数名称：自定义发送模板参数的名称，必须为英文，为请求里的 Key。

  • 显示名称：在「创建计划－触达配置」页面里显示的名称。

  • 参数类型：目前支持创建的类型为字符串型、文本型、链接、数值型、日期型、图片型、富文本、动态下拉、iframe；其中字符串型不支持插入用户属性；文本型、链接和富文本支持插入用户属性；富文本型还支持插入图片和超链接；数值型包括小数、整数、百分比三种；图片支持绝对、比例的尺寸限制。

  • 添加提示文案：提示运营人员当前参数的输入规范。
  • 添加选项：当参数类型为字符串型、文本型、数值型时，支持添加参数选项。编辑完选项后，可以设置默认项，默认项将会在运营人员配置参数时自动填充到输入框。
  • 设置必填：至少勾选 1 个模板参数作为必填项，运营人员在使用 Webhook 时，必填参数全部填写才能提交。

参数类型-动态下拉参数

  •  能力：
    • 下拉参数为从客户接口实时获取。
    • 下拉除了一级下拉，还支持多级目录树，支持搜索；比如可以做实时可用的优惠券、模板的动态下拉。
    • 下拉参数支持配置参数描述，描述信息会以卡片形式展示在下拉窗口旁，为业务人员选择参数时提供参考。
    • 建议合理设置筛选条件，维持在500个选项以内，以保证易用性和速度。
  • 参数配置：需配置下拉参数获取的地址。支持http和https，统一为Get请求。特别提示：URL常需要携带参数，请注意配置完整。
  • 数据结构示例如下：
    [
    {
        "name":"宠物",
        "value":1,
        "detail":{
            "subtitle":"热销宠物用品",
            "description":"最近1个月的宠物用品销量统计",
            "others":[
                {"label":"猫砂","value":1000}
            ]
        }
    },
    {
        "name":"办公用品",
        "value":2,
        "children":[
            {
                "name":"电脑",
                "value":3, 
				"detail":{
                    "subtitle":"MacBook Pro",
                    "description":""
                }             
	        }
        ]
    }
]
    JS
  • 参数说明：
    参数名参数类型是否必需样例值备注
    nameString是"name": "选项名称"

    下拉菜单中，选项的显示名称。同时该名称与参数信息卡片的标题一致。

    value

    String | Number

    		是"value": 1

    选项值，值必须唯一。

    children

    Arrey

    		否

     "children": [
    {"name": "选项名称1", "value": 3}
    ]

    数组成员为对象，对象结构及属性与外层数据的一致

    detail

    Object

    		否"detail":{
         "subtitle":"参数副标题",
         "description":"描述",
         "others":[
              {
                "label":"补充信息",
                "value":1000
               }
           ]
     }

    参数信息卡片中展示的内容，未填写则不展示对应卡片

  • detail：
    参数名参数类型是否必需样例值备注
    subtitleString否"subtitle": "参数副标题"未填写则不显示
    descriptionString否"description": "参数说明"若填写则显示，未填写则显示：“未填写说明”
    othersArray否

    "others": [
    {"label": "这是字段一", "value": 1000},
    {"label": "这是字段二", "value": 1500}
    ] 

    额外的补充展示字段，未填写则不显示。

    数据结构为数组，成员为对象，对象属性如下表。

    在页面上均作为单独一行文本进行显示。

  • others：
    参数名参数类型是否必需备注
    labelString否补充字段的标签名
    valueString｜Number否补充字段的标签值
  • 返回数据结构：前端基于此结构提供下拉选择组件（树形下拉选择），示例如下：
    interface Option {
    name: string;
    value: string | number;
    detail?: {
      subtitle?: string;
      description?: string;
      others?: {
        label: string,
        value: string | number
      }[];
    };
    children?: Option[];
}

type Data = Option[];
    JS
  • 注意：只有具有「detail」字段的尾结点才会展示卡片
  • 页面效果如下：

参数类型-iframe

  • 能力：

    • 点击配置项时，呼出页面来进行选择。可以在此页面中定制各种复杂操作，页面逻辑，最终返回一个选择的最终结果。

    • 结果会以字符串形式回显。
    • 再次打开时，之前的选择操作会回传到 iframe页面，iframe自行处理（例如定位到之前的选项位置）。
  • 参数配置：需配置下拉参数获取的地址。支持http和https，统一为Get请求。
  • 数据交互：
    • 打开 iframe 时 url 上会携带参数，参数可以自定义名称，但必须是静态值。例如 type，value，`${url}?type=${XXX}&value=${value}` 。

    • iframe 向 Webhook 配置页传递数据：

      window.parent.postMessage({
    type: 'XXX', // url 链接上传过来的 type 字段
    value: '来自 iframe 的消息' // 需要传递给 Webhook 的字符串
}, '*');
      JS
  • 特别提示：URL常需要携带参数，请注意配置完整。

高级设置 - 配置参数

Webhook为开发者提供更灵活的参数配置，可添加多个参数，满足企业更多使用上的需求。

  • 一个batch包含的消息数量：支持自定义每次对接口调用传输的消息量。默认为50，支持输入正整数，限制为 1-1000 。如有调整需求，建议联系神策技术进行
  • SecretToken：支持接口认证密钥。输入无特殊限制。
  • 超时判断：支持自定义接口调用的超时时间。毫秒级的时间粒度，默认为10000毫秒，支持切换正整数输入；增加或者减少的箭头是按照秒单位来进行增加或者减少，最大上限为1分钟。
  • 开启压缩请求：支持对下游传输数据进行压缩。默认为否，不开启。
  • 是否校验批量请求结果：支持是否进行校验的设置。
    • 如果选是，即对下游接口的调用成功后（HTTP 200），会对 response body 做解析，来检查每条消息的发送状态，从而计算发送成功和发送失败的条数。注意，返回的 body 格式需符合神策规范。
    • 默认为否，即对下游接口的调用成功后（HTTP 200），认为所有消息都发送成功。需要注意的是，在该选项下，若测试发送的消息最终送达失败，则不会展示失败信息。
  • 发送频率限制（次/秒）：支持发送频率的限制。支持正整数的切换，默认为不限制；切换到自定义时，默认为 1。支持在通道开启时编辑。
  • Batchsize 最大值：支持配置每批消息包含的最大消息数，默认 50。支持在通道开启时编辑。
  • 引擎异常重发：
    • 高速模式：默认选项。如果某批数据发到一半引擎异常，会导致未发的数据丢弃，不再重发。
    • 可靠模式：由于系统问题导致的数据发送异常，同批数据会整体重新发送。请注意：重发的同批数据可能部分已经成功传输到下游，下游系统要做好去重工作。

保存

  • 完成所有设置以后，提交保存，以下为配置的一个样例，供参考：

  • 在创建计划－触达配置选择该 Webhook 的配置界面，如下图：

测试发送

  • 账号创建之后，默认关闭，可以先进行测试发送，确定能发送成功后再开启账号。
  • 点击测试发送，填写测试发送信息。
  • 点击下一步，预览之后发送，稍后右上角会返回发送回执，若发送成功，会返回成功信息；若仍未收到，可点击下载日志查看原因。

Webhook 管理

开启关闭 Webhook 账号

添加 Webhook 账号后，默认关闭，需要手动开启。

  • 账号开启后，新建计划或流程画布时可使用该账号。
  • 账号关闭后，新建计划或流程画布时不可使用该账号，已建计划或流程画布的处理逻辑如下
    • 关闭时将出现弹窗提醒，其会展示受影响的计划或流程，确认关闭后将暂停受影响的计划和流程。同时对于使用了已关闭账号的计划或流程，以下几种情况将引导用户切换通道或重新开启通道
      • 启动暂停中的计划或流程，且这些计划或流程使用了已关闭通道。
      • 编辑暂停中的计划或流程，且这些计划或流程使用了已关闭通道。
      • 复制使用了已关闭通道的计划或流程。
      • 编辑使用了已关闭通道的流程画布的草稿。

编辑 Webhook

  • 已添加账号支持查看、编辑
    • 编辑账号需要：将账号关闭后，才可以编辑。若编辑操作（如透传字段增减）影响了已建计划或流程，则对这些受影响的计划或流程进行编辑、启动、复制等操作时提醒用户进行确认或修改。
  • 根据实际运营需求，可添加多个 Webhook，如对接站内信、对接权益系统等。

删除 Webhook

删除账号需要：将账号关闭后，才可以删除。删除账号后，使用了该账号的计划和流程仍支持查看，若对这些受影响的计划或流程进行编辑、启动、复制等操作将引导切换账号。

接口和数据格式

Webhook 的接口对接文档详见 Webhook 通道接入 。