# Webhook 腳本
## 概述
透過自訂的 webhook 腳本，與第三方服務整合系統，有助於簡化繁複的流程，提升整體系統的效率。這種方式允許您自定義應對特定事件的行為，使系統更具彈性並適應特定需求。整合 webhook 可以實現即時的資料傳遞，促進系統之間的協作，同時也簡化了數據處理流程，提供更好的使用者體驗。
Webhook 的概念是基於事件驅動的架構，當特定事件發生時，系統會主動通知註冊了該事件的 Webhook URL。因此，在使用 Webhook 腳本時，您需要瞭解如何設定 Webhook URL，以及如何處理接收到的事件通知。
{% hint style="warning" %}
在使用 Webhook 腳本之前，建議您具備基礎的 API 整合能力，包括對 Restful API 的請求方式的了解，以及一些基本的設定，如 Header 設定、Params 設定等。如果您曾使用過 postman 或其他 API 測試工具，這將對理解 Webhook 的操作方式有所幫助。
如果您對 API 整合還不太熟悉，建議您事先了解一些相關的基本概念和操作方式，以確保順利使用 Webhook 腳本進行第三方服務整合。
{% endhint %}
## 建立 Webhook 腳本
### 新增腳本
您可以進行以下步驟來新增 Webhook 腳本：
1. 前往「應用程式」功能。
2. 在應用程式中找到「整合」分類。
3. 點擊「Webhook 腳本」功能。
4. 在介面中尋找「新增」按鈕，點擊它。
這樣您就可以開始新增您的第一筆自動化資料。在新增過程中，可能需要填寫一些必要的資訊，例如 「選擇使用場景」、「名稱」等。請根據系統的提示進行操作，以完成 Webhook 腳本的新增。
| 名稱 | 解釋 |
| ------ | ------------------------------------------- |
| 選擇使用場景 | 場景將決定你能讀取的相關資料，建立後無法再更動。你可以選擇如「客戶」、「工單」等情境。 |
| 名稱 | Webhook 腳本的識別名稱。 |
## 設定請求方式
而介面中的 Request 設定項目，可以大略分成三個區塊，分別是 網址，參數，表頭，將構成一次的 API 請求，而個區塊項目如下：
### **網址區塊：**
* **請求 API 路徑 URL：** 定義了 API 的端點或資源位置。例如，`https://api.example.com/users`。
* **Method 請求方法：** 代表了對該 URL 的操作，包括 GET（取得資料）、POST（新增資料）、PUT（更新資料）、DELETE（刪除資料）等。
### **Header 表頭：**
用來設定 Header 中的其他參數，常見的項目有以下資訊
* **User-Agent：** 告知 Server 請求的 Client 的相關資訊，包括瀏覽器、作業系統等。
* **Accept：** 告知 Server 客戶端能夠接受的回應內容類型。
* **Content-type：** 告知 Server 客戶端提交的內容類型，尤其在 POST 或 PUT 請求中。
這些元素共同形成了一個完整的 API 請求，確保正確且有效的資訊交換。
### **Params 參數**
Params 是在 API 要求中設定的參數，通常用於定義特定的搜尋條件、篩選條件或其他需要在 API 請求中指定的數值。而系統中根據不同事件提供對應的「佔位符」功能，這是一個很有彈性的功能，能夠將相關的資料帶入參數中。
例如，在「客戶」的使用場景中，可以在 Params 輸入 `{{ contact.first_name }}`，這樣當觸發相應的事件時，系統會自動將客戶的名字帶入該參數。
這樣的機制提供了更動態且個人化的 API 請求方式，讓您能夠更有效地操作和利用相關資料。
{% hint style="info" %}
「佔位符」 可能不會顯示您所自訂的所有資料欄位，舉例如下：
1. 對於交談腳本中的變數，假設您在腳本中設定了一個名為 `has_message` 的變數，您可能需要在 `params` 區塊中手動輸入 `{{ has_message }}` 以傳遞資料。
2. 對於自訂欄位資料，例如您設定了一個名為「身高」的自訂欄位，您可以輸入 `{{czCol.15 }}` 來傳遞資料。這裡的數字 15 是「身高」自訂欄位的系統編號，可以在自訂欄位介面中查找。需要注意的是，根據不同的觸發來源，可能需要加上前綴。例如，對於「客戶」來源，不需要加上 `contact` 前綴，因為它本身就是觸發來源且是對應自身。但若是其他來源，要取得「客戶」的自訂欄位資料時，則需要使用 `{{ contact.czCol.15 }}`。
請注意，這些方法可能會在將來被廢棄，因此建議您隨時關注我們的更新公告，以獲得最新的資訊。
{% endhint %}
系統編號，您可以在自訂欄位介面中查找。
## 觸發 Webhook 腳本
當您新增好一筆 Webhook 腳本後，您可以透過以下方式來觸發：
1. **透過「自動化腳本」功能觸發：** 在不同的場景下，您可以使用「自動化腳本」功能，例如當工單建立時或其他特定條件下，觸發相應的 Webhook 腳本。
2. **透過「交談腳本」動作節點觸發：** 如果您使用了聊天機器人，您可以在相應的對話流程中使用「交談腳本」的動作節點，以觸發特定的 Webhook 腳本。這可以根據不同的聊天機器人情境和流程來進行觸發。
這樣的觸發方式提供了靈活性，讓您能夠根據需求和情境有效地使用 Webhook 腳本。
{% hint style="warning" %}
為了防止系統資源遭到濫用，或因過度觸發超出系統處理能力，我們針對 Webhook 設置了每分鐘觸發次數上限、等待時間限制與重試次數動態控制，以確保所有用戶能公平地使用系統資源，並維持整體平台穩定性。\
\
注意，這種限制的目的是防止某些情況下的濫用。**例如，如果您設定了當客戶更新時觸發 Webhook，再透過 Webhook 觸發 API 更新同一筆客戶資料，可能產生無窮迴圈**，這將可能觸發上限機制。在正常使用情況下，您應該不太會遇到觸發數限制的問題。
{% endhint %}
## 請求限制與說明
當系統執行 Webhook 腳本並呼叫您所設定的請求路徑時，請特別留意以下執行規則：
1. **回應時間限制：**請求請於 5 - 10 **秒內完成回應**，否則將視為逾時（timeout）並視同失敗。
**實際的重試次數與間隔時間將根據當時系統負載動態調整**，回應時間限制最短 5 秒。
{% hint style="success" %}
## **最佳實踐建議**
👋 你好！這裡是來自技術團隊的說明。
過去我們對 Webhook 的設計採取**彈性等待時間範圍 5–80 秒** \[1] ，是基於伺服器資源充足時提供的容錯設計。但實務上發現，這樣的彈性安排反而**讓用戶產生誤解與混淆**\[2]，進而對整體整合行為造成誤會，並非當初設計的原意。因此，我們決定改為**統一實施固定等待時間**，以提升穩定性與預期一致性。
***
為協助你順利整合 Webhook 並減少逾時風險，請依照以下原則**最佳化您的應用程式與伺服器設計**：
* **簡化處理流程，邏輯精簡為原則**\
收到請求後，處理流程越短越好。確認 payload 資料後，應快速執行必要邏輯，避免過多判斷與重複驗證。
* **避免同步阻塞操作**\
避免在 webhook 執行時進行不必要的同步操作，如寫入大量資料、外部 API 呼叫或產生報表等，這些行為會造成整體延遲。
* **將高延遲或非必要動作移出主流程**\
非即時必要的操作（如通知、報表產生、大量資料處理等）應在 webhook 回應成功後另行處理，避免阻塞主流程。
* **避免多層串接與等待流程**\
應避免 webhook 執行期間串接太多系統、等候回應，**例如：Webhook 呼叫後 → 執行業務邏輯 → 呼叫其他 API → 等待處理完成 → 回傳**，建議流程為收到請求後立即回應 200 OK，後續交由非同步機制處理。若與機器人或自動化流程整合，建議將邏輯拆解為多個節點，而非在單一 webhook 呼叫中一次執行全部步驟。
* **初步驗證完成就立即回應**\
完成基本資料格式與簽章/token 驗證後，即可立即回應成功，確保 webhook 發送端不因等待過久導致逾時。
* **複雜任務交給背景處理或佇列系統**\
大型或非即時的任務應透過背景處理工具（如 RabbitMQ、Celery 等）執行，確保 webhook 主流程回應快速、不被拖累。
* **檢查伺服器負載狀況**\
當資料格式、資料量或請求量沒有明顯變多或異動，但回應卻變得緩慢或不穩定，請檢查伺服器的 CPU、記憶體、磁碟或網路資源是否接近上限，並評估是否需要限流、升級或橫向擴充伺服器。
等，檢查與加強你的程式碼與伺服器邏輯，以提升 Webhook 整合的整體可靠性與處理效率。
***
\[1] max(5, min(80, 80 × (1 - 負載率)))
\[2] 於 2.74.09 版本更新文件已有提前說明
{% endhint %}