⛓️Webhook 腳本

概述

透過自訂的 webhook 腳本，與第三方服務整合系統，有助於簡化繁複的流程，提升整體系統的效率。這種方式允許您自定義應對特定事件的行為，使系統更具彈性並適應特定需求。整合 webhook 可以實現即時的資料傳遞，促進系統之間的協作，同時也簡化了數據處理流程，提供更好的使用者體驗。

Webhook 的概念是基於事件驅動的架構，當特定事件發生時，系統會主動通知註冊了該事件的 Webhook URL。因此，在使用 Webhook 腳本時，您需要瞭解如何設定 Webhook URL，以及如何處理接收到的事件通知。

在使用 Webhook 腳本之前，建議您具備基礎的 API 整合能力，包括對 Restful API 的請求方式的了解，以及一些基本的設定，如 Header 設定、Params 設定等。如果您曾使用過 postman 或其他 API 測試工具，這將對理解 Webhook 的操作方式有所幫助。

如果您對 API 整合還不太熟悉，建議您事先了解一些相關的基本概念和操作方式，以確保順利使用 Webhook 腳本進行第三方服務整合。

建立 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 請求方式，讓您能夠更有效地操作和利用相關資料。

「佔位符」 可能不會顯示您所自訂的所有資料欄位，舉例如下：

1. 對於交談腳本中的變數，假設您在腳本中設定了一個名為 has_message 的變數，您可能需要在 params 區塊中手動輸入 {{ has_message }} 以傳遞資料。

2. 對於自訂欄位資料，例如您設定了一個名為「身高」的自訂欄位，您可以輸入 {{czCol.15 }} 來傳遞資料。這裡的數字 15 是「身高」自訂欄位的系統編號，可以在自訂欄位介面中查找。需要注意的是，根據不同的觸發來源，可能需要加上前綴。例如，對於「客戶」來源，不需要加上 contact 前綴，因為它本身就是觸發來源且是對應自身。但若是其他來源，要取得「客戶」的自訂欄位資料時，則需要使用 {{ contact.czCol.15 }}。

請注意，這些方法可能會在將來被廢棄，因此建議您隨時關注我們的更新公告，以獲得最新的資訊。

系統編號，您可以在自訂欄位介面中查找。

觸發 Webhook 腳本

當您新增好一筆 Webhook 腳本後，您可以透過以下方式來觸發：

1. 透過「自動化腳本」功能觸發： 在不同的場景下，您可以使用「自動化腳本」功能，例如當工單建立時或其他特定條件下，觸發相應的 Webhook 腳本。

2. 透過「交談腳本」動作節點觸發： 如果您使用了聊天機器人，您可以在相應的對話流程中使用「交談腳本」的動作節點，以觸發特定的 Webhook 腳本。這可以根據不同的聊天機器人情境和流程來進行觸發。

這樣的觸發方式提供了靈活性，讓您能夠根據需求和情境有效地使用 Webhook 腳本。

為了防止系統資源遭到濫用，或因過度觸發超出系統處理能力，我們針對 Webhook 設置了每分鐘觸發次數上限、等待時間限制與重試次數動態控制，以確保所有用戶能公平地使用系統資源，並維持整體平台穩定性。 注意，這種限制的目的是防止某些情況下的濫用。例如，如果您設定了當客戶更新時觸發 Webhook，再透過 Webhook 觸發 API 更新同一筆客戶資料，可能產生無窮迴圈，這將可能觸發上限機制。在正常使用情況下，您應該不太會遇到觸發數限制的問題。

請求限制與說明

當系統執行 Webhook 腳本並呼叫您所設定的請求路徑時，請特別留意以下執行規則：

1. 回應時間限制：請求請於 15 秒內完成回應，否則將視為逾時（timeout）並視同失敗。

2. 自動重試機制：若請求失敗（包含逾時），系統將自動嘗試重新發送 1～3 次。

實際的重試次數與間隔時間將根據當時系統負載動態調整，最低可能僅重試 1 次，回應時間限制最短 5 秒。

最佳實踐建議

👋 你好！這裡是來自技術團隊的說明。

過去我們對 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 版本更新文件已有提前說明}