← 所有文章
教學

LINE Webhook 多事件批次:如何處理部分失敗

LINE Messaging API 的一個 webhook 請求可以包含多個事件,而且可能來自不同用戶。不要只處理 events[0],不要把整個請求歸到第一位發送者,也不要只儲存部分事件就回傳成功。應先驗證簽署、持久化接收所有事件,然後回傳 200。以每個事件的 webhookEventId 去重,避免重複投遞造成重複業務操作。

重點

  • 一個 HTTP 請求不一定只對應一個事件、用戶或對話。
  • HTTP 確認涵蓋整個請求,儲存和處理記錄則要細分到事件。
  • deliveryContext.isRedelivery 是診斷資訊,不是去重鍵。
  • LINE 重送不能代替持久化封存,也不能代替應用程式自己的工作重試。

為甚麼只處理第一個事件會漏接

LINE 的開發指南明確指出:用戶 A 的訊息事件與用戶 B 的關注事件,可以出現在同一個 webhook。Messaging API 參考定義了請求的 events 陣列及當中的事件物件。

層級代表甚麼錯誤捷徑
HTTP 請求正在驗證和確認的一次投遞第一個事件成功就當作全部成功
事件物件有獨立類型、來源及 ID 的事件將第一個事件的發送者或訊息欄位套用至其他事件

按每個事件自己的 type 和 source 分流。關注事件不是「缺少文字的訊息」。頂層 destination 代表接收機械人的身分,不是整批事件共同對應的客戶。

空陣列是另一種有效的連線驗證情況,詳見空 events 驗證指南。本文處理的是非空批次在接收途中部分失敗的問題。

所有事件持久化後,才確認請求

先按 LINE 的簽署驗證指南,使用 channel secret 對原始請求內容驗證 x-line-signature,通過後才解析 JSON。請求應綁定實際用於驗證的 channel 設定,不應從第一個事件決定客戶或租戶。

建議使用資料庫支援的事件收件表:

  1. 檢查外層結構,以及每個事件接收所需的識別欄位。
  2. 在同一個資料庫交易內寫入每個事件,以應用程式的 channel 範圍和 webhookEventId 組成唯一鍵。
  3. 已存在的鍵視為已接收,不要將現有處理狀態重設為待處理。
  4. 提交交易後才回傳 200,背景工作另行讀取已提交的記錄,處理較慢的業務操作。

以下 JavaScript 只示範這個邊界。inbox.transaction 和 tx.insertIfAbsent 是應用程式自行實作的抽象,不是 LINE 方法或 SDK;實作必須有真正的交易和唯一約束。channelKey 來自可信的接收器設定,輸入已通過驗證。

async function acceptVerifiedLineBatch(payload, channelKey, inbox) {
  if (!payload || !Array.isArray(payload.events)) {
    throw new Error('Invalid events array');
  }
  for (const event of payload.events) {
    if (!event || typeof event.webhookEventId !== 'string' ||
        event.webhookEventId.length === 0 ||
        typeof event.type !== 'string') {
      throw new Error('Invalid event envelope');
    }
  }

  await inbox.transaction(async (tx) => {
    for (const event of payload.events) {
      await tx.insertIfAbsent(channelKey, event.webhookEventId, event);
    }
  });
  return 200;
}

這並非完整 HTTP 伺服器。呼叫端仍須拒絕無效簽署、處理解析錯誤,並確保驗證或提交失敗時不會回傳成功。遇上暫時儲存故障,可選擇回傳 503 等非 2xx 狀態,但這只是應用程式的策略,不保證 LINE 能補回每個事件。

不要在沒有復原機制的情況下,先寫收件表,再獨立發佈至佇列。兩次寫入之間中斷,可能令已確認的工作無法被發現。讓背景工作直接讀取持久化收件表,或透過交易式 outbox 派發。

復原部分失敗,不依賴整批身分

LINE 的接收指南指出事件可能重複,建議使用 webhookEventId 偵測。重送時保留事件 ID,但 deliveryContext.isRedelivery 會改變。不要假設同一組事件一定再次一起到達,也不要以整個 HTTP 內容的雜湊值作業務去重鍵。

以下以假設批次中的 A、B 事件說明:

失敗位置建議處理
儲存 B 時交易失敗回復本交易的新寫入,不確認成功
A 已在之前的請求中儲存保留 A 的原有記錄,仍然接收 B
提交成功但 HTTP 回應遺失重複事件找到現有記錄,不新增工作
HTTP 成功後背景工作失敗從本地收件表重試,不等待 LINE 重送
收到合法但未支援的事件類型儲存後安排受控檢查,不靜默丟棄其他事件

若現有實作逐條提交,應保留已寫入記錄,並在重複投遞時去重。第一條插入成功不代表整個請求完成。

背景工作重試也要有獨立保護。CRM 更新或回覆可能已成功,但工作尚未記錄完成就中斷。應保留不確定結果,並在下游支援時使用其文件定義的冪等機制。回覆方面,reply token 復原指南解釋了為何重複事件不代表全新、獨立的回覆機會。

分開 LINE 重送限制與 UnifyPort 契約

LINE 重送需要啟用相關功能,並且 webhook 回應失敗。官方不公開重試次數及間隔,也明確不保證重送一定可靠送達。事件到達次序亦可能不同於發生次序。保留事件 timestamp 作為判斷背景,不要把陣列位置當成全域次序。

UnifyPort 的非官方介面是獨立的訊息帳戶接入方式。標準事件封裝使用 id、type、provider、account_id、occurred_at 和 data,不是 LINE 原生 events 陣列。投遞契約在設定 signing_secret 後使用 X-Device-Signature,任何 2xx 回應均會確認投遞。

可以共用持久化收件表設計,但不可混用解析器或簽署字串。缺少原生 events 欄位不等於空陣列驗證請求。如果發送身分必須是 LINE 官方帳戶,應保留官方 Messaging API;更換整合方式不能修復已部分接收的請求。

常見問題

一個事件失敗,還可以回傳成功嗎?

只有在所有事件已持久化接收,而失敗屬於可由本地復原的後續處理時才可以。若尚有事件未儲存,就不應確認整個請求成功。

應否丟棄所有 isRedelivery 事件?

不應該。它可能是你第一次成功收到的副本,應查閱持久化去重記錄。

Promise.all 能令批次處理安全嗎?

不能。並行操作仍可部分成功。安全性來自持久化接收、唯一事件鍵及復原機制,不是 JavaScript 的排程方式。

下一步與參考資料

建議測試混合用戶批次、現有事件與新事件並存、提交失敗、確認回應遺失,以及背景工作中斷。這些是待執行測試,不是已驗證結果。獨立的 UnifyPort 接收器請從 webhook 投遞參考開始。

官方來源核對日期:2026-11-13。

UnifyPort API

令訊息接入變成一條穩定嘅產品管線。

先用統一嘅 API 跑通發送,再用標準事件將所有入站訊息接返去業務系統。