WebHook
WebHook
- 接口文档变更记录
第几次变更 | 变更内容 | 变更人 |
---|---|---|
1 | 1、增加客服号上下线记录接口 | 陈超 |
2 | 1、增加接口加密逻辑说明(header 方式) | 陈超 |
3 | 1、webhook 接口迁移到 API 目录下面 | 陈超 |
WebHook 接入规范
注意: 要接入 webhook API,请联系客户成功人员(提供对应的配置 webhook 的地址、类型)进行配置,或者自行通过 webhook 相关接口进行配置。
1、交互流程
2、接口安全规范
联系管理员获取秘钥、公司 id(SalesEpoch 管理后台获取)
接口请求加密方式-1
此接口加密方式,加密字段是放到接口的请求体( body) 里面。
1、把 tenant_id+timestamp+密钥当做签名字符串(access_token),使用 HmacSHA256 算法计算签名。
String appSecret = "f9a40a4780f5e1306c46f1c8daecee3b";
String tenantId = "500975";
String timestamp = "1666942813620";
String message = tenantId + timestamp ;
String access_token = HmacSHA256Util.hmacSHA256(appSecret,message);
// 小写
// str = df98eda524132837317c5ea7e4f67ef4224dedc3f01548b6cb211b08eb0328c5
- 接口请求加密方式-2
此接口加密方式,加密字段是放到请求头( header) 里面。
1、把 tenant_id+timestamp+密钥当做签名字符串(access_token),使用 HmacSHA256 算法计算签名。
String appSecret = "f9a40a4780f5e1306c46f1c8daecee3b";
String tenantId = "500975";
String timestamp = "1666942813620";
String message = tenantId + timestamp ;
String access_token = HmacSHA256Util.hmacSHA256(appSecret,message);
// 小写
// str = df98eda524132837317c5ea7e4f67ef4224dedc3f01548b6cb211b08eb0328c5
注: 202406 之后的新接口全部使用第二种加密方式(请求头传递参数)。
java HmacSHA256 加密,可以引用 common-codec(1.15)包。
public static String hmacSha256(String apikey, String message) {
return (new HmacUtils(HmacAlgorithms.HMAC_SHA_256, apikey.getBytes(StandardCharsets.UTF_8))).hmacHex(message.getBytes(StandardCharsets.UTF_8));
}
3、HTTP 状态码
均以 code 为准
Code | 描述 | 详细解释 |
---|---|---|
200 | ok | success! |
4、公共参数
参数名 | 类型 | 是否必填 | 备注 |
---|---|---|---|
accessToken | String | 是 | 签名字符串 token |
tenantId | int | 是 | 公司 id |
timestamp | Long | 是 | 毫秒时间戳 |
5、常见问题
通知失败重试次数
说明:通知进行同步后,不响应或不为 200 的状态码均为失败,5 次以上将关闭该类型的 WebHook 配置信息.
配置关闭如何处理
说明:关闭配置后,仍进行数据的采集但不进行同步,当配置打开后以 10 分钟为间隔进行一次检测,检测到打开
后进行同步所有的历史数据。
时区
UTC+8
WebHook 相关接口
📢 此文档涉及到的 webhook 接口,可单独联系客服或者管理员进行配置,也可使用以下接口自行配置。
查询配置的 WebHook
URI
/wscrm-bus-api/open/webhook/getConfList
请求方式
POST、Content-Type: application/json
说明
请求参数说明
参数名 | 类型 | 是否必填 | 备注 |
---|---|---|---|
tenantId | Long | 是 | 公司 id |
- 请求示例
{
"tenantId": 500766
}
- 响应参数说明
参数名 | 类型 | 备注 |
---|---|---|
code | int | 响应码 |
message | String | 响应信息 |
data | String | 数据 |
- 响应示例
{
"code": 200,
"message": "Success",
"data": [
{ "type": "MSG_SYNC_MESSAGE", "url": "http::/api.bus.com/syncUserInfo" }
]
}
新增(修改) Webhook 配置
URI
/wscrm-bus-api/open/webhook/add
请求方式
POST、Content-Type: application/json
说明
请求参数说明
参数名 | 类型 | 是否必填 | 备注 |
---|---|---|---|
tenantId | Long | 是 | 公司 id |
info | Object | 是 | 详情数据 |
data 参数说明
参数名 | 类型 | 是否必填 | 备注 |
---|---|---|---|
type | String | 是 | 类型(具体的参考下面的类型表) |
url | String | 否 | 接口地址 |
- 请求示例
{
"tenantId": 500766,
"info": {
"type": "MSG_SYNC_MESSAGE",
"url": "http://api.bus.com/syncMessage"
}
}
- 响应参数说明
参数名 | 类型 | 备注 |
---|---|---|
code | int | 响应码 |
message | String | 响应信息 |
data | String | 响应数据 |
- 响应示例
{
"code": 200,
"message": "Success",
"data": ""
}
修改 WebHook 配置状态
URI
/wscrm-bus-api/open/webhook/updateConfigStatus
请求方式
POST、Content-Type: application/json
说明
请求参数说明
参数名 | 类型 | 是否必填 | 备注 |
---|---|---|---|
tenantId | Long | 是 | 公司 id |
info | Object | 是 | 详情数据 |
info 参数说明
参数名 | 类型 | 是否必填 | 备注 |
---|---|---|---|
type | String | 是 | 类型 |
status | String | 是 | 状态 0、正常 1、关闭 |
- 请求示例
{
"tenantId": 500766,
"info": {
"type": "MSG_SYNC_MESSAGE",
"url": "http://api.bus.com/syncUserInfo"
}
}
- 响应参数说明
参数名 | 类型 | 备注 |
---|---|---|
code | int | 响应码 |
message | String | 响应信息 |
data | String | 响应数据 |
- 响应示例
{
"code": 200,
"message": "Success",
"data": ""
}
WebHook 配置 Type 列表
文档中接口标注 webhook 类型,且<配置 Id>为下面列表中的值时,可使用接口进行管理。
type | 描述 |
---|---|
USER_SYNC_PORTRAIT | 用户画像修改同步 |
MSG_SYNC_MESSAGE | 收发消息 |
USER_WRITE_FLOW | 写跟进 |
GROUP_IN_OR_OUT_GROUP | 进退群行为 |
GS_SYNC_TASK_STATUS | 群发状态同步 |
GS_V3_REPLY_MESSAGE | 群发消息回复同步 |
GS_V3_SYNC_TASK_STATUS | 群发任务状态同步 |
GS_V3_SYNC_TASK_DETAIL_STATUS | 群发任务详情状态同步 |
WA_SYNC_ON_OR_OFF_LINE_STATUS | WhatsApp 客服号上下状态同步 |
CHANNEL_SYNC_STATUS | channel 客服号状态同步 |
CHANNEL_REGISTER_STATUS | channel 注册状态同步 |