← 所有文章
教學

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 跑通傳送,再用標準事件把所有入站訊息接回業務系統。