← 全記事
チュートリアル

LINE Webhookの複数イベント:バッチの一部が失敗した場合の処理

LINE Messaging APIの1つのwebhookリクエストには、異なるユーザーのイベントを含む複数のイベントが入ることがあります。events[0]だけを処理したり、全件を最初の送信者に紐付けたり、一部だけ保存して成功を返したりしてはいけません。署名検証後に全イベントを永続化し、その後で200を返します。重複処理は、各イベントのwebhookEventIdを使って防ぎます。

要点

  • 1つのHTTPリクエストが、1イベント、1ユーザー、1会話とは限りません。
  • HTTP応答はリクエスト全体への確認ですが、保存と処理状態はイベント単位で管理します。
  • deliveryContext.isRedeliveryは診断情報であり、重複判定のキーではありません。
  • LINEの再送は、永続的な履歴保存やアプリ側のワーカー再試行の代わりにはなりません。

最初のイベントだけでは取りこぼす理由

LINEの開発ガイドラインには、ユーザーAのメッセージイベントとユーザーBのフォローイベントが同じwebhookに含まれる例が明記されています。Messaging APIリファレンスは、events配列と各イベントオブジェクトを定義しています。

境界意味誤った処理
HTTPリクエスト認証し、受信確認する配信最初のイベントの成功を全体の成功とみなす
イベントオブジェクト独自の種類、送信元、IDを持つイベント最初の送信者やメッセージ項目を他のイベントにも使う

各イベント自身のtypeとsourceで振り分けます。フォローイベントは「本文がないメッセージ」ではありません。トップレベルのdestinationは受信するボットの識別子であり、全イベントが属する顧客ではありません。

空配列は、これとは別の有効な接続確認ケースです。空のeventsを扱う検証ガイドを参照してください。ここでは、空ではないバッチの受け入れが途中で失敗する場合を扱います。

全件の永続化を受信確認の条件にする

まずLINEの署名検証ガイドに従い、チャネルシークレットと未変更のリクエストボディでx-line-signatureを検証します。JSONの解析はその後です。リクエストは検証に使ったチャネル設定に紐付け、最初のイベントから顧客やテナントを選ばないようにします。

推奨する構成は、データベース上の受信イベントテーブルです。

  1. 外側の構造と、全イベントの受け入れに必要な識別項目を検証する。
  2. 1つのデータベーストランザクションで各イベントを保存する。アプリ側のチャネル識別子と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応答が失われる同じイベントIDは既存行に対応し、新しい仕事を作らない
HTTP成功後にワーカーが失敗LINEの再送を待たず、自分の受信テーブルから再試行する
有効だが未対応のイベント種類が届く保存して管理下で確認し、他のイベントを黙って捨てない

既存実装が1件ずつコミットしている場合は、保存済みの行を維持し、再配信時に重複を排除します。最初の挿入が成功しただけでリクエスト全体を完了扱いにはできません。

ワーカーの再試行には別の対策も必要です。CRM更新や返信が成功した直後、完了記録の前に停止する可能性があります。不明な結果は不明のまま保持し、下流が対応する場合はその文書化された冪等性機能を使います。返信については返信トークンの復旧ガイドで、重複イベントが新しい独立した返信機会ではないことを確認してください。

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を維持します。連携先の変更は、部分的に受け入れたリクエストの復旧手段ではありません。

FAQ

1つのイベントが失敗しても成功を返せますか?

全イベントを永続化済みで、失敗が自分のシステムで復旧できる後続処理にある場合に限ります。未保存のイベントがあるなら、リクエスト全体の受信成功を返すべきではありません。

isRedeliveryがtrueなら捨ててよいですか?

いいえ。初めて正常に受信できたコピーかもしれません。永続化された重複判定記録を確認します。

Promise.allでバッチは安全になりますか?

いいえ。並行処理でも一部だけ成功することがあります。安全性は永続化、一意キー、復旧の仕組みによって決まります。

次のステップと出典

異なるユーザーの混在、保存済みと新規イベントの混在、コミット失敗、確認応答の消失、ワーカー停止をテストしてください。これは提案するテストであり、実施済みの結果ではありません。別途UnifyPortを受信する場合はwebhook配信リファレンスから始めます。

公式資料の確認日:2026-11-13。

UnifyPort API

メッセージ連携を安定したプロダクトパイプラインへ。

まずは 1 つの API で送信を始め、標準イベントですべての inbound メッセージを業務システムへ戻しましょう。