# Webhook 整合指南

## 概述

當您在**機器人流程中透過 Webhook 呼叫外部服務**時，若因以下原因造成請求逾時（Timeout）：

* 技術實作尚未最佳化
* 同一個呼叫中執行過多步驟且**需等待回應**（如同步建立訂單、寫入資料庫等）
* 伺服器效能不足或延遲高

就可能導致 Webhook 在規定的等待時間內未收到回應，進而產生逾時錯誤。

例如：流程中呼叫建立訂單的 API，若該 API 需要等待完整建立流程執行完畢才回傳結果，就很容易導致 Webhook 請求超出等待上限。

本篇將說明幾個**改善 Webhook 整合效能與穩定性的方式**，協助避免因單一請求包辦過多處理而導致的逾時問題。

{% hint style="warning" %}

## **機器人流程整合提醒**

**當你在機器人流程中呼叫 Webhook 時，流程將暫停等待 Webhook 回應完成，期間內的顧客訊息將不會被進一步觸發處理**。

舉例來說：當顧客表達想查找資料，並透過 Webhook 呼叫外部服務進行處理，此時若回應時間較長，而顧客在等待期間持續補充訊息，這些訊息**將不會被即時傳遞或處理**，恐導致上下文斷裂、回應不連貫。

若欲整合第三方大型語言模型（LLM），請務必考量上述限制，評估是否符合您對即時互動與對話完整性的需求。

***

**在實際對話流程中，讓顧客等待超過 10 秒而無任何後續回應，將嚴重影響互動體驗與信任感，這在設計上是不可接受的情境。**

**請在進行流程整合或 API 呼叫設計時，務必將使用者體驗納入優先考量。整合的目的應是提升反應效率與一致性，而非僅為了技術可行性或嘗試「突破系統限制」而犧牲整體體驗。**

* **若整合流程需要較長時間，可設計中間回覆（如「請稍候，我們正在查詢」）。**
  {% endhint %}

## ✅ 拆解步驟、非同步處理

為避免 Webhook 在單一呼叫中執行過多需要等待的操作（如建立訂單、串接外部系統），導致請求逾時，建議採用以下處理方式：

**將多個處理步驟進行拆解，改為分段執行：**

1. 在流程中呼叫 API 後，**先立即回傳 `200 OK`**，避免阻塞或等待過久造成逾時。
2. 接續插入一個 **「等待」節點**，例如延遲 20 秒，用來預留外部處理時間。
3. 等待結束後，再透過另一個 **Webhook 節點或 API 呼叫**，主動查詢或嘗試取得處理結果。

透過這樣的設計方式，能夠有效避免一次性同步處理過多邏輯造成的超時問題，同時保留流程控制與後續銜接能力。

<figure><img src="/files/lfVrGyMEJ7Q2mDmJLzXk" alt=""><figcaption></figcaption></figure>

## ✅ 進階建議：提升顧客體驗的訊息節點設計

在上述流程中，若您希望讓顧客感受到流程正在進行、非系統延遲，也可以加入**訊息提示節點**來優化體驗：

* **在等待節點前，穿插一個「發送訊息」節點**，主動告知顧客目前的處理進度\
  例如：「訂單正在建立中，請稍候...」

這樣的設計不僅能減少用戶等待期間的不確定感，也有助於降低因等待造成的反覆提問或中斷操作。

## ✅ 進階技巧：結合 Webhook 回傳結果 + 條件判斷節點

若你的外部系統回應時間不固定，建議可以進一步設計一組「**回應結果判斷邏輯**」，提升流程彈性與反應效率：

**📌 實作方式：**

1. **在首次 Webhook 呼叫時**，由對方系統回傳一段結果資訊，例如：

```json
{
  "result": "success",
  "order_id": "123456"
}
```

2. **在流程中插入一個條件判斷節點**，根據回傳結果中的 `result` 值進行判斷：
   * 若為 `success`，則直接進入後續回應流程，顯示結果或通知用戶
   * 若為 `pending` / `null` / `failed`，則走原本的等待＋重查路徑（如等待 20 秒後再次呼叫 webhook 查詢）

這樣的設計方式能夠**有效減少不必要的等待時間**，讓成功的流程能夠**立即結束並回應用戶**，而失敗或尚未完成的情況，則透過等待與補查機制**再進一步處理**。

整體來說，這種做法提供了更大的彈性來**應對外部系統回應時間不穩定的狀況**，同時也實現了**流程穩健、不中斷、可預期**的整合體驗，是實務上非常推薦的進階整合策略之一。

<figure><img src="/files/eaWzyVymaUMPfPax8X1w" alt=""><figcaption></figcaption></figure>

## 總結

Webhook 的使用受到以下限制規則影響：包括每分鐘觸發次數上限、單次請求的等待時間上限，以及同時最大處理中的請求數（併發限制）等。

若您將 Webhook 應用於高頻率請求的情境，需特別留意可能產生的排隊效應。例如：<mark style="background-color:yellow;">**若每筆請求平均回應時間接近 15 秒，排隊中的其他請求也將被迫依序等待前一筆處理完成，進而導致級聯延遲效應**</mark>，使整體回應效率大幅下降。

因此，我們仍建議您依照標準流程設計 webhook 結構，採取快速回應、背景處理等方式優化整合效率。

{% hint style="warning" %}

#### ⚠️ 針對長延遲回應的潛在影響

1. **LINE Reply Token 限制：**&#x82E5;您整合的是 **LINE 官方帳號**，請注意其 Reply Token 有效時間僅約 **30 秒**。Webhook 若未能於此時間內完成回應，將無法透過即時回覆完成互動，需額外透過推播訊息補發，**可能產生額外費用與使用體驗落差**。
2. **轉換率與使用者體驗損失：**&#x5EF6;遲的互動回應將直接影響使用者在銷售流程中的停留與行動，可能導致： 使用者中途離開或放棄填寫表單、客服回應滿意度降低、實際轉換率與營收流失
3. **平台可信度下降與技術懲罰風險**：部分第三方平台（如 slack、Facebook、Stripe 等）為確保整體服務品質，會對 webhook 回應時間設有嚴格要求。若整合方未能於規定時限內完成回應，平台可能視為服務不穩定，進而觸發技術層面的懲罰機制，例如降低 webhook 通知頻率、暫停事件發送等。
4. **級聯延遲效應**：當 webhook 回應時間過高（如需 40 秒以上）時，將產生排隊等待效應，造成後續訊息處理延遲。尤其在 webhook 同時僅允許有限數量併發處理的情境下，若有多位使用者同時互動，系統將依序排隊處理，導致第二位、第三位顧客的訊息可能被延遲數十秒甚至超過一分鐘。明顯影響整體回應即時性，降低使用者體驗，並進一步放大平台回應逾時與轉換率流失的風險。

...等，我們建議務必優化整合架構、採快速回應機制，否則後續若導致訊息遺失、互動錯誤或平台懲罰。
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.firstline.cc/feature/chatbot/scenario/example/webhook-zheng-he-zhi-nan.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.