表单线索Webhook接入文档

通过webhook配置，可以向您推送灵蹊表单数据，Webhook是一个http请求回调接口，需要您的团队按照以下方式提供实现；灵蹊后台服务器收到表单数据请求时，会去回调该接口，并把表单数据以json格式推送到您的服务器。 

配置Webhook 

1. 在灵蹊页面编辑器中，表单->选中表单，打开表单设置，开始配置Webhook 
2. 输入Webhook 描述信息，用来区分该表单对应的Webhook描述 
3. 输入Webhook url，用来接收回调接口推送的数据。 
4. 输入Secret Key，用来确认请求身份 
   （注： Webhook url 只支持https协议） 

接口和请求格式 

1. 请求方法

支持http post请求方法

2. 请求头

请求头内容：

Content-Type: application/json; charset=utf-8
User-Agent: Lingxi-Webhook/1.0
X-Lingxi-TraceId: xxxxxx-xxxx-xxxx-xxxx-xxxxxxx
X-Lingxi-Sign:xxxxxxxxxxxxxxx

（注： Sign= sha256(Secret_key + timestamp)) ） 

请求头字段说明：

1. X-Lingxi-TraceId 
   每个请求唯一标识，开发人员可以使用请求中的该字段来定位请求排查错误。 
2. X-Lingxi-Sign 
   该字段提供了一种安全验证方式，用于防止请求伪造（CSRF攻击），灵蹊服务端在推送表单数据的时候，以Secret key结合其它请求字段计算出Sign值，Webhook实现端用同样的算法计算该Sign，两者需要对比一致。 

3. 请求体

灵蹊默认发送的请求体格式如下。如需自定义请求体格式，请参见下一节中的描述。

{
timestamp:1581567704707,
data:{
PAGE_URL:"https://www.lingxi.com",
FORM_NAME:"表单名称1",
PAGE_REFERRER:"来源地址",
PAGE_START: 1599462682478,
STAY_TIME:1000,
IP:"101.1.6.140",
field1:value1,
field2:value2,
....
},
meta:{
field1:{
type:'String',
}
field2:{
type:'Number'
}
}
}

请求体字段说明：

1. Timestamp：
   时间戳，和Secret Key组合用于Sign值的计算 
2. test:true
   在页面预览时，可以推送测试数据检查Webhook，将携带此信息
3. data：
   表单数据，以key-value方式组合，key为表单设置中名称的值 
   1. PAGE_URL 内置字段，请求包体必带（表单所在页面地址）
   2. PAGE_TITLE 内置字段，请求体必带（表单所在页面的页面名称，注意，为页面列表所见的管理用名称，非发布时对外的标题）
   3. FORM_NAME 内置字段，请求体必带（提交数据所属表单名称）
   4. PAGE_REFERRER 内置字段，请求体必带（表单页面的来源地址）
   5. PAGE_START 内置字段，请求体必带（请求开始时间）
   6. STAY_TIME 内置字段，请求体必带（提交表单时，页面停留时间）
   7. device 内置字段，请求体必带，值为pc / mobile
   8. IP 内置字段，请求体必带（终端客户IP）
   9. PAGE_VERSION 内置字段，非请求体必带（提交表单时，用户所访问到的创意版本信息）
   10. meta：
       元数据信息，提供表单字段的基本类型描述 

灵蹊会持续增加推送字段以方便提供更多线索洞察，请避免使用过度严格的匹配方式，防止后续接口更新时出现接收失败。您可以在接收时忽略不需要的字段，只选择收录特定字段

4. 自定义请求体格式

如果上一节中描述的请求体格式不能满足需求，可以通过配置Webhook的“消息格式”来进行自定义。

在Webhook配置界面中的“消息格式”部分，输入JSON格式的格式配置，例如：

{
"timestamp":"${timestamp}",
"data":{
"PAGE_URL": "${PAGE_URL}",
"FORM_NAME": "${FORM_NAME}",
"PAGE_REFERRER": "${PAGE_REFERRER}",
"PAGE_START": "${PAGE_START}",
"STAY_TIME": "${STAY_TIME}",
"姓名": "${姓名}",
"微信": "${微信}",
"手机号码": "${手机号码}",
"邮箱": "${邮箱}"
}

其中用${ }包裹的部分为表单中字段的名称，在实际数据推送过程中，会被替换为字段的具体内容。${PAGE_URL}等为内置字段。

注意事项

1. 避免要求特定字段“必填”和“特定格式”。
   在灵蹊前端可以进行必填和格式校验，由于业务端在制作表单时偶尔会灵活调整所用字段以实验转化效果，当表单使用的字段和推送要求的字段不匹配时会导致线索无法及时录入您的数据库。
2. 避免因接受字段超出预设而拒收
   随着灵蹊的产品升级，推送内容可能发生变动，增加更多有用的推送字段（例如增加流量来源、表单发生时的创意版本等），您可以在收录数据时只提取自己所需的字段，但避免因为字段组合不匹配自己的收录值时拒收数据，避免造成线索无法录入。
3. Webhook成功/失败状态应同业务接收逻辑一致，避免错误回复200代码
   灵蹊对Webhook的推送状态设有失败告警，当发生告警，灵蹊将第一时间将问题同步给您方便排查。因此，为了线索数据正常收录以及告警能够及时、正确发挥作用，请根据您的业务逻辑来配置您Webhook的接收状态。
   如果您的业务库需要在接收线索后再进行二次加工筛选入库（例如接收后只收录具备“门店位置”信息的线索），建议先将灵蹊线索全部收录至中间库再进行加工处理，如果您没有中间库、而是在接收数据成功后再由业务库抛弃不符合条件的数据，请避免向灵蹊错误回传标识成功的200代码，应以一致逻辑告知灵蹊推送失败，方便使用灵蹊的市场团队成员及时发现问题并作出对应（例如发现特定页面的“门店位置”缺失导致推送失败，应当及时修改表单设计），避免出现持续丢失线索但无法发觉。
4. 灵蹊推送失败后会自动重试，请处理好线索排重
   为了最大程度确保为您完整推送线索，灵蹊将在推送失败后自动重试。如果遇到网络堵塞导致超时，灵蹊无法及时收到成功信息，灵蹊重试推送可能会造成您的服务器多次收到信息，请务必做好线索排重。
5. 如出现线索库处理规则调整，也请及时同步至您使用灵蹊的团队成员调整表单
   随着您的业务发展，线索库的收录规则也可能会动态升级，请在升级时及时同步相关变更至您使用灵蹊的团队成员，避免与现有的表单设计存在冲突，引发线索推送失败。（不过请安心，即使推送失败的数据，在灵蹊中仍有收录，不会丢失，只需接口理顺后重新推送）
6. 如果你设置了防火墙，请将联系我们，将灵蹊IP加入您的白名单