跳到主要内容

Webhook使用说明

什么是Webhook?

Webhook,也被称为反向API。

传统的API,通常是由客户方主动发起调用,API服务器返回数据,或执行某个指令。

Webhook API与之相反,不是由客户主动调用,而是由Webhook发送请求,客户被动接受来自Webhook的请求和数据。

GoEasy Webhook主要用于帮助客户服务器能够实时接收来自GoEasy的相关数据。

当前支持:

同步IM消息历史

同步PubSub消息历史

工作流程

  1. GoEasy数据发生变化
  2. GoEasy发送请求到客户指定的URL
  3. 客户收到来自GoEasy的请求
  4. 验证请求的合法性(防止欺骗攻击)
  5. 客户处理数据(比如入库)
  6. 返回response(code必须是200)
  7. 完成

如何启用Webhook?

  1. 在自己的服务端实现一个接受GoEasy Webhook请求的服务器接口
  2. 登录GoEasy控制台,进入应用详情,配置URL,保存并启用即可

实现接口接收GoEasy Webhook的请求

  1. 实现一个http接口,必须是能接受post请求,该接口不可以有任何访问限制,确保能收到来自GoEasy Webhook的请求
  2. 验证请求的合法性(防止欺骗攻击)
  3. 获得数据 String content = request.getParameter("content") request中参数content的值,即为发送过来的JSON格式的字符串,数据格式参考具体的webhook api
  4. 处理数据 建议在收到数据后,快速入库或者发送到消息队列,确保在3秒内返回response, 否则将会造成请求超时,对于超时的请求,GoEasy会进行三次尝试,三次失败后,将会停止该webhook所有的数据发送。 如果有复杂的业务逻辑需要处理,建议用异步方式处理,不要进行长时间的同步逻辑处理。
  5. 返回值 请求处理完成后,返回的 response 必须符合是以下格式:
    • 内容为 {"code":200,"content":"success"}
    • Response返回的httpcode必须为200 否则GoEasy会视为发送失败,会反复发送同样的请求。
  6. 停止发送和重新启用 GoEasy webhook在发送数据时,可能会遇到以下服务不可用,及数据无法成功送达的情形:
    • 客户服务器重启
    • 网络不稳定
    • 发送请求超时 GoEasy将会进行三次尝试,三次重试后,GoEasy依然无法得到httpcode为200的response,webhook将停止发送数据,遇到数据发送停止,开发者可以登录GoEasy控制台, 重新启用webhook.
  7. 数据顺序 为了获得更好的并发发送性能,GoEasy发送过来的数据并不是一个绝对的有序,但都包含相应的时间戳。
  8. 数据重复 考虑到网络环境的不稳定,为了确保消息能够送达客户服务器,GoEasy webhook可能会重复发送同一条请求,建议开发者对所收到的消息进行一定的去重操作,每个webhook api发送的数据都会有唯一标识字段。