[TOC] ***** # webhook ## 什么是webhook？ ——webhook（也被称为网络回调或HTTP推送API）是一个应用为其他应用提供实时信息的一种方法。 ——当webhook被触发后，它将传送数据到其他应用程序中去，该应用程序会立即获取到数据，而不需要定时调用当前应用的openAPI批量获取数据。 ## Linkflow webhook 动作 ——在Linkflow客户旅程中使用webhook动作图元，当客户旅程被触发，webhook可以向配置地址发起请求，将客户旅程触发事件信息、联系人信息、自定义信息发送给配置地址。 ## 配置webhook 动作图元 1. 在客户旅程画板上，拖入webhook动作图元  2. 点击设置按钮，填写信息  ***** **消息接收URL**：请填写接收消息地址 **请求方法**：目前只支持post方法 **消息格式**：目前只支持JSON **消息结构体配置**：您可以在此自定义消息结构体中的参数 * 用户详情 选择：消息结构体增加contact参数 不选择：消息结构体contact参数中只有id * 关注状态用户微信账号 选择：contact结构体中增加wechatAccounts参数 不选择：contact结构体中没有wechatAccounts参数 * 用户自定义连接账号 选择：contact结构体中增加udcAccounts参数 不选择：contact结构体中没有udcAccounts参数 * 触发事件 选择：消息结构体中增加event、eventMetadata参数 不选择：消息结构体中没有event、eventMetadata参数 * 自定义参数 选择：消息结构体中增加_custom参数 不选择：消息结构体中没有_custom参数 当您勾选自定义参数选项，并添加了自定义参数，就可在_custom结构体中解析出您的自定义参数。 **示例**： ~~~ { "sendTime": 1553249452973, "contact": { "id": 100, "name": "张三", "mobilePhone": "13912341234", "email": "zhangsan@example.com", "wechatAccounts": [ { "appId": "appid1", //微信公众账号appid "openId": "openId1", //联系人openid "unionId": "unionId1" //联系人unionId }, { "appId": "appid2", "openId": "openId2", "unionId": "unionId2" } ], "udcAccounts": [ { "externalId": "externId1", //联系人在自定义渠道的账号 "channelId": "abc.com", //自定义渠道连接的channelid "channelName": "abc website" //自定义渠道连接的名称 } ] }, "event": { "eventDate": 1553249452973, "channelId": "wx123", "channelName": "微信mp", "event": "WECHAT__SUBSCRIBE", "attr1": "XXX", "attr2": "XXX", "contactId":18257, "id":104298, "items": [] }, "eventMetadata": [ { "appCode":"WECHAT", "eventCode":"WECHAT__SCAN_QRCODE", "eventName":"扫描二维码", "attr4Type":"text", "attr4Name":"推广人ID", "attr5Type":"text", "attr5Name":"推广人姓名", "attr6Type":"enum:QRCodeType", "attr6Name":"二维码类型", "attr9Type":"text", "attr9Name":"二维码ID", "hasItem":false, "hasUtm":true } ], "_custom": { "foo": "bar" } } ~~~ ***** **1 消息结构体参数字段含义** | 字段名 | 类型 | 描述 | 示例 | | --- | --- | --- | --- | | sendTime | long | 请求时间 | 1553249452973 | |contact | object | 联系人 | 参见1.1联系人结构体参数字段 | | event | object | 触发事件 | 参见1.2事件结构体参数字段 | | eventMetadata | list | 事件metadata列表 | 参见1.3事件metadata结构体参数字段 | | _custom | object | 自定义参数 | | **1.1联系人结构体参数字段含义** | 字段名 | 类型 | 描述 | 示例 | | --- | --- | --- | --- | | id | string | 联系人ID | 1553249452973 | | name | string | 联系人姓名 | 张三 | | mobile | string | 联系人手机 | 15150000000 | | email | string | 联系人邮箱 | zhangsan@demo.com | | wechatAccounts | list | 联系微信账号列表（公众号、小程序） | | | udcAccounts | list | 联系人自定义渠道账号列表 | | ***** **1.2事件结构体参数字段含义** | 字段名 | 类型 | 描述 | 示例 | | - | ----- | ----------- | --- | | id | string | 事件id | 104298 | | eventDate | long | 时间戳：事件发生时间 | 1554798374000 | | channelId | string | 连接id | udc\_1544vOULeekh | | channelName | string | 连接名称 | 源犀科技 | | event | string | 事件编码 | WECHAT__SUBSCRIBE | | sdkVersion | string | SDK的版本 |1.0.0 | | sdkType | string | 记录此事件的SDK | iOS SDK | | platform | string | 应用平台 | iOS | | screenWidth | BigDecimal | 屏幕宽度 | | | screenHeight | BigDecimal | 屏幕高度 | | | appVersion | string | 应用版本 | | | bundleKey | string | 应用包名 | | | os | string | 操作系统 | Linux | | osVersion | string | 操作系统版本 | 例如8.1.1 | | browser | string | 浏览器名称 | 谷歌浏览器 | | browserVersion | string | 浏览器版本 | 11 | | country | string | 国家 | 中国 | | province | string | 省份 | 江苏| | city | string | 城市 | 南京 | | networkType | string | 网络类型 | WiFi | | manufacturer | string | 设备供应商 | 三星| | deviceModel | string | 设备类型 | iPhone | | operator | string | 运营商 | 中国联通 | | debugMode | Boolean | 是否是测试数据 | true | | imei | string | IMEI | | | ip | string | ip地址 | | | latitude | BigDecimal | 纬度 | | | longitude | BigDecimal | 经度 | | | attr1 | 根据事件编码，查找事件metadata中的属性类型 | 事件属性值 。可根据事件编码，查找事件metadata中的属性定义 | | | attr2 | 根据事件编码，查找事件metadata中的属性类型 | 事件属性值 。可根据事件编码，查找事件metadata中的属性定义 | | | attr3 | 根据事件编码，查找事件metadata中的属性类型 | 事件属性值 。可根据事件编码，查找事件metadata中的属性定义 | | | attr4 | 根据事件编码，查找事件metadata中的属性类型 | 事件属性值 。可根据事件编码，查找事件metadata中的属性定义 | | | attr5 | 根据事件编码，查找事件metadata中的属性类型 | 事件属性值 。可根据事件编码，查找事件metadata中的属性定义 | | | attr6 | 根据事件编码，查找事件metadata中的属性类型 | 事件属性值 。可根据事件编码，查找事件metadata中的属性定义 | | | attr7 | 根据事件编码，查找事件metadata中的属性类型 | 事件属性值 。可根据事件编码，查找事件metadata中的属性定义 | | | attr8 | 根据事件编码，查找事件metadata中的属性类型 | 事件属性值 。可根据事件编码，查找事件metadata中的属性定义 | | | attr9 | 根据事件编码，查找事件metadata中的属性类型 | 事件属性值 。可根据事件编码，查找事件metadata中的属性定义 | | | attr10 | 根据事件编码，查找事件metadata中的属性类型 | 事件属性值 。可根据事件编码，查找事件metadata中的属性定义 | | | attr11 | 根据事件编码，查找事件metadata中的属性类型 | 事件属性值 。可根据事件编码，查找事件metadata中的属性定义 | | | attr12 | 根据事件编码，查找事件metadata中的属性类型 | 事件属性值 。可根据事件编码，查找事件metadata中的属性定义 | | | attr13 | 根据事件编码，查找事件metadata中的属性类型 | 事件属性值 。可根据事件编码，查找事件metadata中的属性定义 | | | attr14 | 根据事件编码，查找事件metadata中的属性类型 | 事件属性值 。可根据事件编码，查找事件metadata中的属性定义 | | | attr15 | 根据事件编码，查找事件metadata中的属性类型 | 事件属性值 。可根据事件编码，查找事件metadata中的属性定义 | | | attr16 | 根据事件编码，查找事件metadata中的属性类型 | 事件属性值 。可根据事件编码，查找事件metadata中的属性定义 | | | attr17 | 根据事件编码，查找事件metadata中的属性类型 | 事件属性值 。可根据事件编码，查找事件metadata中的属性定义 | | | attr18 | 根据事件编码，查找事件metadata中的属性类型 | 事件属性值 。可根据事件编码，查找事件metadata中的属性定义 | | | attr19 | 根据事件编码，查找事件metadata中的属性类型 | 事件属性值 。可根据事件编码，查找事件metadata中的属性定义 | | | attr20 | 根据事件编码，查找事件metadata中的属性类型 | 事件属性值 。可根据事件编码，查找事件metadata中的属性定义 | | | items | list | 子事件。| | | utm | object | utm参数。 | { "source":"wechat", "medium":"qrcode", "content":"联否ALPHA", "term":"1" ,"campaign":"营销活动3"} | | contactId | long | 事件联系人id | 18257 | ***** **1.3事件metadata结构体参数字段含义** | 字段名 | 类型 | 描述 | 示例 | | --- | --- | --- | --- | | id | string | 事件metadata id | 1 | | appCode | string | 事件所属链接类型。如：扫描二维码事件属于微信 | WECHAT | | eventCode | string | 事件编码 | WECHAT__SUBSCRIBE | | eventName | string | 事件名称 | 扫描二维码 | | attr1Name | string |事件属性名称 | | | attr1Type | string | 1.3.1事件属性类型 | | | attr2Name | string | 事件属性名称 | | | attr2type | string | 1.3.1事件属性类型 | | | attr3Name | string | 事件属性名称 | | | attr3type | string | 1.3.1事件属性类型 | | | attr4Name | string | 事件属性名称 | | | attr4type | string | 1.3.1事件属性类型 | | | attr5Name | string | 事件属性名称 | | | attr5type | string | 1.3.1事件属性类型 | | | attr6Name | string | 事件属性名称 | | | attr6type | string | 1.3.1事件属性类型 | | | attr7Name | string | 事件属性名称 | | | attr7type | string | 1.3.1事件属性类型 | | | attr8Name | string | 事件属性名称 | | | attr8type | string | 1.3.1事件属性类型 | | | attr9Name | string | 事件属性名称 | | | attr9type | string | 1.3.1事件属性类型 | | | attr10Name | string | 事件属性名称 | | | attr10type | string | 1.3.1事件属性类型 | | | attr11Name | string | 事件属性名称 | | | attr11type | string | 1.3.1事件属性类型 | | | attr12Name | string | 事件属性名称 | | | attr12type | string | 1.3.1事件属性类型 | | | attr13Name | string | 事件属性名称 | | | attr13type | string | 1.3.1事件属性类型 | | | attr14Name | string | 事件属性名称 | | | attr14type | string | 1.3.1事件属性类型 | | | attr15Name | string | 事件属性名称 | | | attr15type | string | 1.3.1事件属性类型 | | | attr16Name | string | 事件属性名称 | | | attr16type | string | 1.3.1事件属性类型 | | | attr17Name | string | 事件属性名称 | | | attr17type | string | 1.3.1事件属性类型 | | | attr18Name | string | 事件属性名称 | | | attr18type | string | 1.3.1事件属性类型 | | | attr19Name | string | 事件属性名称 | | | attr19type | string | 1.3.1事件属性类型 | | | attr20Name | string | 事件属性名称 | | | attr20type | string | 1.3.1事件属性类型 | | | hasItem | Boolean | 是否有子事件 | false | **1.3.1事件属性类型值定义** | 值 | 含义 | 说明 | | --- | --- |--- | | text | 字符串 || | integer | 整数 || | number | 数字 || | datetime | 日期 || | enum | 枚举 | 按照string处理 | | reference | 引用 | linkflow内部引用id，按照string处理 | ## 推送规则 当工作流被触发，webhook工作被触发，linkflow会向配置地址发起请求。 1、消息推送服务通过 POST 、参数编码为 JSON 的方式向开发者提供的地址推送消息； 2、开发者接收到消息后需要在10秒内回复code为 200的响应； 3、当推送没有成功返回会进入重发，最多重发三次。 规则是无法连通或者返回的http code 大于等于500（服务器异常）； 4、消息推送成功的逻辑是开发者服务器返回200。 ## 场景举例 场景描述：需要将每个加入标签组“webhook”的联系人同时同步到外部的服务器（如阿里云服务器等） 流程设计如下：   然后发布流程，凡是加入此标签组的人员均可以同步到外部服务器。 **注：联系人信息可以实时同步到外部服务器，如网络缓慢问题，数据同步会稍后延后。** ## 接口鉴权 1、当webhook配置的接口需要鉴权时，您可前往设置-App集成设置-授权设置中，配置一个用于获取令牌的授权，授权的配置请参考：https://www.kancloud.cn/linkflowtech/lfcs/2164899 2、勾选webhook的启用鉴权功能，在下方填入需要鉴权的请求参数，令牌的值可以使用通配符#{auth.授权标识.令牌的key}获取（通配符外也可拼接空格与字符串）您需要根据您配置的授权返回结构自行判断填写令牌的key。