Webhook使用说明 - GoEasy

什么是Webhook？

Webhook，也被称为反向API。

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

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

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

GoEasy Webhook目前支持的功能包括：

1. 消息历史同步
2. 客户端上下线状态变化（快速推进中，敬请期待）

GoEasy Webhook是如何工作的？

GoEasy数据发生变化 -> GoEasy发送请求到客户指定的URL -> 客户收到来自GoEasy的请求 -> 验证请求的合法性（防止欺骗攻击） -> 客户处理数据（比如入库）-> 返回response(code必须是200）-> 完成

如何启用GoEasy 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发送的数据都会有唯一标识字段。