← 全記事
ガイド

UnifyPort のアカウント Webhook:ワークスペースにイベントが届かない理由

UnifyPort のワークスペース Webhook に他のメッセージングアカウントのイベントは届くのに、特定のアカウントだけ届かない場合は、そのアカウント専用の Webhook 設定を確認してください。アカウント設定はワークスペース設定より優先されます。 専用エンドポイントが inactive でも、対象イベントを購読していなくても、ワークスペースへの自動フォールバックはありません。最後の専用エンドポイントを削除すると、その後の初回配信に対して継承が復元されます。過去のイベントが再送されるという意味ではありません。

要点

  • ワークスペース用とアカウント用は別の設定スコープであり、主系と待機系ではありません。
  • アカウント指定なしの一覧はワークスペース用だけを返すため、両方を照会します。
  • アカウント用の一覧が空でも、有効な受信経路がないとは限りません。
  • 無効化しても専用設定は残ります。継承の復元には最後の専用エンドポイントの削除が必要です。
  • 経路選択、購読、署名検証、アカウントの接続状態を別々に確認します。

どの設定がイベントの送信先を決めるのか

Webhook エンドポイント作成リファレンスでは、リクエスト本文の任意フィールド account_id を定義しています。指定すると新しいエンドポイントはそのアカウントに紐付き、省略するとワークスペース用になります。レスポンスではアカウント専用エンドポイントに account_id が入り、ワークスペース用では省略されます。

アカウント専用設定ワークスペースの継承確認対象
専用エンドポイントなし適用されるワークスペース側の状態と購読
active で購読も一致専用設定が優先専用受信サービスと署名設定
専用設定がすべて inactive自動フォールバックなし専用設定を残す意図
active だが対象イベントを購読していない自動フォールバックなし専用エンドポイントの購読
最後の専用エンドポイントを削除済み以後の初回配信で継承を復元ワークスペースの準備と新規イベント

たとえば、ワークスペース側は message.received、ある LINE アカウントの専用エンドポイントは account.status.updated だけを購読しているとします。これは仮の設定例であり、実際の障害報告ではありません。ワークスペースの購読が、専用設定から漏れたメッセージイベントを補完することはありません。専用設定を修正するか、継承を復元するかを選びます。

イベントフィルターの解説は購読名の選択を扱います。その前に必要なのが、このアカウントの配信を担当するスコープはどちらかという確認です。

2 回の読み取り専用リクエストで確認する

サーバー側で保持する同じ X-Api-Key を使います。このキーがワークスペースを決めます。以下はリクエストパスの例です。acc_example はアカウント照会で得た実際の公開 ID に置き換えてください。

GET /v1/webhook-endpoints
GET /v1/webhook-endpoints?account_id=acc_example

Webhook エンドポイント一覧によると、前者はワークスペース用だけ、後者は指定アカウントの専用設定だけを返します。後者に継承先のワークスペース設定は含まれません。成功レスポンスの data: [] は「専用設定なし」であり、「Webhook の受信経路なし」ではありません。

エンドポイント ID、アカウントの紐付け、URL、status、subscribed_events、signing_enabled、再試行設定を記録します。inactive の項目も継承に影響するので確認してください。秘密情報やメッセージ本文は診断記録に残しません。

パラメーター名は正確に account_id とします。空値、空白のみ、重複、大文字小文字の変更は省略と同じ扱いではありません。明示したアカウントが存在しない、または別のワークスペースに属する場合は 404 account_not_found です。空の一覧と解釈せず、ID とワークスペースを修正します。

両方の設定が正しければ、認証状態と runtime 状態を別々に確認し、対応する新規イベントを受信側の認証と永続保存まで追跡します。誤った URL に届かないことを理由に、正常なアカウントを再起動しないでください。

専用設定を修復するか、継承を復元するか

アカウント専用の受信先を維持する

Webhook エンドポイント更新で、既存の URL、有効状態、購読を修正します。確認済みの署名設定と再試行設定を保持してください。空の signing_secret は署名を無効化するため、署名なしのサンプルを本番にコピーしないでください。

同じアカウントに active の専用エンドポイントがある状態で、別の active エンドポイントを作成すると、409 account_webhook_already_exists、数値コード 40008 が返る場合があります。別のエンドポイントを inactive から active にする場合も同様です。既存の active を active のまま更新することは可能で、過去から複数の active 設定が残っている場合も対象です。古い重複設定が自動整理されるとは考えないでください。この制限はワークスペース用には適用されません。

アカウントの紐付けは変更できません。更新時の account_id は元の所有関係を検証するだけで、省略するとその関係を維持します。省略や null でアカウント用をワークスペース用に変換したり、既存のワークスペース用をアカウントに割り当て直したりはできません。

ワークスペースの受信先に戻す

まず、ワークスペースの受信先が active で、必要なイベントを購読し、署名検証と永続保存の準備ができていることを確認します。専用ワークフローの担当者とも影響を確認してください。

その後、Webhook エンドポイント削除で専用設定を明示的に廃止します。inactive を含め、残る項目をすべて確認します。inactive が残れば専用設定も残ります。アカウント指定の一覧を再取得し、専用エンドポイントがないことを確認してください。削除成功時は 204 で、レスポンス本文はありません。

これは配信経路の変更であり、通常のメンテナンス手順ではありません。CRM や AI 処理だけを一時停止するなら、Webhook メンテナンスの比較にある下流ワーカーの停止を検討してください。

新しい経路の確認と、復旧の限界

設定変更後に、管理された新しいテストメッセージを送ります。予定した受信先でアカウントとイベントを確認し、配信仕様に従って署名を検証します。永続保存後に受信確認を返し、下流処理は別途検証します。

これは推奨する受け入れ確認であり、実際のワークスペースで実施済みのテストではありません。設定変更リクエストがタイムアウトした場合は、再実行前に現在の状態を読み取ります。継承ルールは以後の初回配信を対象としており、処理中のすべてのリクエストの挙動までは示していません。

UnifyPort の非公式インターフェースはイベントを共通形式で届けますが、欠落したペイロードの再送を保証しません。新規テストの成功は新経路の確認であって、以前の欠落期間が復旧した証明ではありません。

よくある質問

専用エンドポイントを無効化すれば継承に戻りますか?

いいえ。inactive の専用設定もワークスペースより優先されます。最後の専用エンドポイントを削除すると、以後の初回配信で継承に戻ります。

ワークスペースの購読をワイルドカードにすれば解決しますか?

アカウント設定の優先関係は変わりません。有効な専用設定を修正するか、意図的に削除して継承を復元してください。

アカウント用の一覧が空なのはなぜですか?

成功した空の結果は専用設定がないことを示します。ワークスペースの一覧で継承先を確認します。エラーレスポンスは空の結果ではありません。

次のステップと資料

変更前にWebhook エンドポイント一覧で両方のスコープを比較してください。

公式製品資料の確認日:2026-11-15。

UnifyPort API

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

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