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.updated）		客服修改對話小結
建立顧客（client.created）		建立顧客、訪客轉換為顧客
更新顧客（client.updated）		在工作臺更新顧客引數
刪除顧客（client.deleted）		客戶在【顧客】刪除顧客

簽名校驗的具體流程如下：

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