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 注册状态同步