为自动旅程快速接入其他触达通路

2021-07-23 33723

Webhook通道接入

简介 / 原理

自动化营销系统，除了内置提供的包括短信、微信等多种触达通路之外，还支持有一定自研能力的外部系统通过较为轻量级的REST API的形式对接其他触达通路。这种对接方式，称之为Webhook。

接入步骤

1、在营销系统中定义Webhook通道并配置相关参数。
2、在旅程对应触达节点中选择指定的Webhook。
3、在您的系统中开发一个HTTP Server，处理由营销系统推送过来的信息，实现自定义业务逻辑。应遵循的API定义见下文。

遵循API定义

Webhook Request

营销系统通过HTTP方式请求您的接口，具体Request结构如下：

POST /your/path HTTP/1.1
Content-Type: application/json
Content-Length: 2737
Host: 10.42.34.43:8999
Connection: Keep-Alive
User-Agent: Apache-HttpAsyncClient/4.1.3 (Java/1.8.0_212)

{"messageId":"3f","version":"1.0","timestamp":"","userProfile":{...},"journeyInfo":{...},"params":{...}}

Request Body请求信息遵循如下格式：

{
    "messageId":"34fefaa0-6f02-45e6-a9e1-d9d361b041bf",					// 消息唯一ID，唯一标识一条消息
    "version":"1.0",																						// 系统版本信息
    "timestamp":"1618386204486",																// 消息发送时间戳
    "userProfile":{																							// 用户属性相关信息，系统默认发送
        "orgId":"26615263",																					// 租户ID
        "appId":"generic",																					// APPID
        "userId":"26615263:0",																			// 用户ID
        "affId":"1542197767534286",																	// 爱番番ID，在爱番番系统下唯一身份标识
        "openId":"oQpLS5tnDrnw1ArNohBI1Jr0xzeI"											// 微信OPEN ID，可能为空
    },
    "journeyInfo":{																							// 旅程相关信息，系统默认发送
        "journeyId":"3a63e4f6-f102-44dd-91a9-c437df43cbd6",					// 旅程实例ID
        "journeyName":"营销拓客旅程",																	// 旅程名称
        "actionDefId":"21064602-466d-4128-bd56-c0ad69f494de",				// 旅程动作节点定义ID
        "actionId":"763ff1ee-d412-4150-b32c-45ed29583582"						// 旅程动作ID
    },
    "params":{																									// 您在 webhook 中配置的自定义参数信息
        "date":"2021-04-20",
        "grade":1,
        "content":"张三您好！"
    }
}

Webhook Response

营销系统接收响应遵循如下格式：

1、HTTP 200 无 Body，营销系统认为请求成功。
2、HTTP 200 有 Body，需要返回结果标识及错误信息。格式如下：

// 成功时
{
  "succeed": true,											// 请求结果标识
  "message": "系统处理成功......"					// 信息
}

// 失败时
{
  "succeed": false,
  "message": "系统处理失败......"
}

3、非 HTTP 200 状态，认为请求失败。

身份认证

一些场景下，为保证请求是来源于Webhook的营销系统，而不是第三方伪造，需要开启鉴权功能。系统支持Basic Auth认证方式。操作步骤如下：

1、在Webhook配置页面选择Basic Auth认证，并填写用户名，密码
2、Webhook自动在Request Header中添加Authorization信息
3、您在系统中需要对Authorization信息中的用户名和密码进行校验，从而保证身份合法

本文导读