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 設定,不應從第一個事件決定客戶或租戶。
建議使用資料庫支援的事件收件表:
- 檢查外層結構,以及每個事件接收所需的識別欄位。
- 在同一個資料庫交易內寫入每個事件,以應用程式的 channel 範圍和
webhookEventId組成唯一鍵。 - 已存在的鍵視為已接收,不要將現有處理狀態重設為待處理。
- 提交交易後才回傳
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。
令訊息接入變成一條穩定嘅產品管線。
先用統一嘅 API 跑通發送,再用標準事件將所有入站訊息接返去業務系統。