API 与 Webhook，其实并没有那么难懂

API 和 Webhook 都允许不同的软件系统同步和共享信息，随着软件应用程序变得越来越相互关联，开发人员必须了解这两种共享数据方式之间的区别，并选择最能满足手头任务需求的工具。

---

API 与 Webhook

有关API和Webhook的概念、区别，互联网上已经有不少解释，本文就不再作过多赘述，仅以两个简单的例子描述其原理，供读者与用户参考：

API采用的是“拉”数据的方式。假设：项目A需要调用项目B的数据，则B要开放一个接口，每当A需要数据的时候，就向B发送请求，通过这个接口获得数据。这个接口就是API；

但麻烦也因此产生了：每当A需要调用数据的时候，都需要发送一遍请求，效率较低；并且A并不知道B什么时候更新数据，无法做到数据的实时同步。

这时候，Webhook的作用就体现出来了。

Webhook“人如其名”，采用的是“钩（hook）”数据的方式。同样是项目A需要项目B的数据，Webhook的方式是需要A提供一个url给B，每当B更新数据时，可以通过Webhook及时将数据传递给A。

美洽如何使用 Webhook

在了解了API与Webhook的作用后，本文将重点介绍美洽是如何使用Webhook的。

正如前文所述，Webhook的特点在于：以事件驱动，可以在发生数据变化时及时回传数据。因此，美洽将Webhook应用在软件工作台的对话、顾客、工单数据等模块。

目前，美洽支持在工作台手动或者自动触发了下列事件之后，主动通知客户的服务器地址，并把相关信息一并返回给客户，以实现实时同步客户数据，但需要客户按要求准备服务器地址，并完成签名校验方可实现：

动作	业务对象	触发事件
结束对话（conversation.closed）	​​Conversation​​	手动或自动结束对话
更新对话（conversation.updated）	​​Conversation​​	客服修改对话小结
创建顾客（client.created）	​​Client​​	创建顾客、访客转换为顾客
更新顾客（client.updated）	​​Client​​	在工作台更新顾客参数
删除顾客（client.deleted）	​​Client​​	客户在【顾客】删除顾客

签名校验的具体流程如下：

1. 读取 HTTP 请求的 Body，将其转换为字符串 body_str；
2. 将 body_str 和 secret 拼接成需要加密的字符串 encrypted_str，body_str 在前， secret 在后；
3. 对 encrypted_str 进行 SHA1 加密得到 signature_str；
4. 将 signature_str 和 HTTP Header 中的 Meiqia-Signature的值进行比对。

参数样例如下：

POST /api/meiqia/notify HTTP/1.1 
Host: 127.0.0.1:5005 
User-Agent: Go-http-client/1.1 
Content-Length: 3140 
Content-Type: application/json; charset=utf-8 
Meiqia-Sign: 44cb7f1e544d8830ab0e1feb959b94b3e02eb7e9 
Accept-Encoding: gzip 


 {    
  "id": "sub_09e4bee581ffbcd347fcf634e0f99df8_1632648830",   //美洽定义的通知唯一标识
  "event": "conversation.updated",                           //主题
  "enterprise_token": "09e4bee581ffbcd347fcf634e0f99df8",    //美洽定义的企业 Token
  "created_at": 1632648830,                                  //通知的创建时间
   "conversation": {                                          //主题的业务对象
         "enterprise_id": 97631,        
         "dev_client_id": null,         
         "page_from_url": "",         
         "search_engine": ""     
         }
}

如果配置成功，则返回状态码如下：

状态码	描述
200	成功，美洽将订阅的主题成功推送到 Webhook URL