跳至主要內容

WebHook

大约 4 分钟

WebHook

  • 接口文档变更记录
第几次变更变更内容变更人
11、增加客服号上下线记录接口陈超
21、增加接口加密逻辑说明(header 方式)陈超
31、webhook 接口迁移到 API 目录下面陈超

WebHook 接入规范

注意: 要接入 webhook API,请联系客户成功人员(提供对应的配置 webhook 的地址、类型)进行配置,或者自行通过 webhook 相关接口进行配置。

1、交互流程

webhook回调业务时序图

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描述详细解释
200oksuccess!

4、公共参数

参数名类型是否必填备注
accessTokenString签名字符串 token
tenantIdint公司 id
timestampLong毫秒时间戳

5、常见问题

  • 通知失败重试次数

    说明:通知进行同步后,不响应或不为 200 的状态码均为失败,5 次以上将关闭该类型的 WebHook 配置信息.

  • 配置关闭如何处理

    说明:关闭配置后,仍进行数据的采集但不进行同步,当配置打开后以 10 分钟为间隔进行一次检测,检测到打开

    后进行同步所有的历史数据。

  • 时区

    UTC+8

WebHook 相关接口

📢 此文档涉及到的 webhook 接口,可单独联系客服或者管理员进行配置,也可使用以下接口自行配置。

查询配置的 WebHook

  • URI

    /wscrm-bus-api/open/webhook/getConfList

  • 请求方式

    POST、Content-Type: application/json

  • 说明

  • 请求参数说明

参数名类型是否必填备注
tenantIdLong公司 id
  • 请求示例
{
  "tenantId": 500766
}
  • 响应参数说明
参数名类型备注
codeint响应码
messageString响应信息
dataString数据
  • 响应示例
{
  "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

  • 说明

  • 请求参数说明

参数名类型是否必填备注
tenantIdLong公司 id
infoObject详情数据

data 参数说明

参数名类型是否必填备注
typeString类型(具体的参考下面的类型表)
urlString接口地址
  • 请求示例
{
  "tenantId": 500766,
  "info": {
    "type": "MSG_SYNC_MESSAGE",
    "url": "http://api.bus.com/syncMessage"
  }
}
  • 响应参数说明
参数名类型备注
codeint响应码
messageString响应信息
dataString响应数据
  • 响应示例
{
  "code": 200,
  "message": "Success",
  "data": ""
}

修改 WebHook 配置状态

  • URI

    /wscrm-bus-api/open/webhook/updateConfigStatus

  • 请求方式

    POST、Content-Type: application/json

  • 说明

  • 请求参数说明

参数名类型是否必填备注
tenantIdLong公司 id
infoObject详情数据

info 参数说明

参数名类型是否必填备注
typeString类型
statusString状态 0、正常 1、关闭
  • 请求示例
{
  "tenantId": 500766,
  "info": {
    "type": "MSG_SYNC_MESSAGE",
    "url": "http://api.bus.com/syncUserInfo"
  }
}
  • 响应参数说明
参数名类型备注
codeint响应码
messageString响应信息
dataString响应数据
  • 响应示例
{
  "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_STATUSWhatsApp 客服号上下状态同步
CHANNEL_SYNC_STATUSchannel 客服号状态同步
CHANNEL_REGISTER_STATUSchannel 注册状态同步
上次编辑于:
贡献者: kubrick