UnifyPort Webhookのイベント絞り込み：subscribed_eventsとワイルドカードの選び方

単一目的の本番ハンドラーでは subscribed_events に必要なイベントを明示し、完全なイベント収集基盤や要件確認中のエンドポイントでは ["*"] を使います。ワイルドカードが対象にするのは公開標準イベントすべてであり、内部のrawイベントではありません。LINEを含む問い合わせ受信箱なら、まず message.received を選び、同じサービスが接続状態も管理する場合だけアカウントライフサイクルイベントを追加するのが実用的です。

要点

• subscribed_events には正確な公開イベント名を指定するか、["*"] だけを指定します。
• 未知のイベント名はエンドポイントの作成・更新時に拒否されます。
• 購読できても、すべてのプロバイダーがそのイベントを生成するとは限りません。
• message.received は受信・送信の両方を表し得るため、data.message.direction を確認します。
• イベントの絞り込み、HMAC署名、応答確認、再試行は別々の制御です。

subscribed_events が制御するもの

UnifyPortは、subscribed_events で選択したイベントをWebhookエンドポイントへHTTP POSTで配信します。標準エンベロープには常に id、type、provider、account_id、occurred_at とイベント固有の data が含まれます。利用できる名前とペイロードは標準イベントカタログで確認できます。

受信処理に必要な最小構成は次のとおりです。

{
  "subscribed_events": ["message.received"]
}

ただし、ハンドラー側には方向判定が必要です。

if (
  event.type === 'message.received' &&
  event.data?.message?.direction === 'inbound'
) {
  await storeInboundMessage(event);
}

このイベントは、接続されたメッセージングアカウントでメッセージが観測されたことを示します。受信専用のイベントではありません。

ワイルドカードは次のように指定します。

{
  "subscribed_events": ["*"]
}

"*" と名前付きイベントを同じ配列に混ぜず、完全な選択として使います。公開標準イベントはすべて対象になりますが、内部のrawイベントは公開されません。

実用的な3つのフィルターパターン

1. 受信箱だけを処理する

顧客から届くメッセージの保存とルーティングだけを担当するサービス向けです。

{
  "subscribed_events": ["message.received"]
}

data.message.direction が inbound のレコードだけを処理します。編集、削除、リアクション、受領通知が必要になった時点で、それぞれの正確なイベント名と保存状態の更新方法を追加します。

2. 受信箱とアカウント状態を同時に監視する

同じサービスで認証切れやランタイム切断も通知する場合の構成です。

{
  "subscribed_events": [
    "message.received",
    "account.status.updated",
    "account.started",
    "account.auth.required",
    "account.auth.succeeded",
    "account.auth.failed"
  ]
}

すべての状態イベントを再起動命令として扱ってはいけません。auth_status と runtime_status を反映し、アカウントの現在値を再確認してから操作します。メッセージングアカウントのランタイム復旧手順では、refresh、reconnect、start、再認証の判断基準を説明しています。

3. 全イベントを保持する収集基盤

エンドポイントを共通の取り込み境界とし、下流で用途別に配信するなら ["*"] が適しています。LINE、WhatsApp、Telegram、TikTok、Zalo、Xを1つの署名付きキューへ入れ、メッセージ、受領通知、グループ、アカウント状態を別々のコンシューマーで処理できます。

ワイルドカード利用時も、将来追加される公開イベントに備えたデフォルト分岐が必要です。エンベロープを安全に保存して成功応答を返し、未対応タイプは監視可能な隔離キューへ送ります。すべてのイベントをメッセージだと仮定しないでください。

明示的なフィルターでエンドポイントを作成する

実際のAPIルートは POST /v1/webhook-endpoints です。次のリクエストは、受信メッセージとアカウント状態を受け取る有効な署名付きエンドポイントを作成します。

curl -X POST https://api.unifyport.ai/v1/webhook-endpoints \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"url\": \"https://inbox.example.com/webhooks/unifyport\",
    \"status\": \"active\",
    \"subscribed_events\": [
      \"message.received\",
      \"account.status.updated\",
      \"account.auth.required\"
    ],
    \"signing_secret\": \"$WEBHOOK_SIGNING_SECRET\",
    \"retry_policy\": { \"max_attempts\": 3 }
  }"

各フィールドはWebhookエンドポイント作成リファレンスに従います。retry_policy.max_attempts は初回配信後の再試行回数です。文書上の既定値 3 なら、初回に加えて最大3回再試行されます。指定可能な範囲は 0 から 5 です。

後からフィルターを変更する場合は、文書化された PATCH /v1/webhook-endpoints/{endpoint_id} に更新後の subscribed_events を送ります。作成時と同じイベント名検証が適用されます。

絞り込みと配信セキュリティを分ける

イベントフィルターは何を送るかを決め、signing_secret は配信に X-Device-Timestamp と X-Device-Signature を付けるかを決めます。署名を有効にした場合、JSON解析前のrawリクエストボディを使い、タイムスタンプ、ピリオド、ボディの順で連結した値のHMAC-SHA256を検証します。

任意の 2xx 応答で配信確認となります。接続エラーとHTTP 408、429、5xx は設定に従って再試行されますが、その他の 4xx は再試行されません。配信はat-least-onceなので、通常イベントの再送は冪等に処理します。

完全な受信実装はWebhook配信と署名検証と、詳しいHMACリプレイ保護・冪等性チュートリアルを参照してください。

イベント名を追加する前にプロバイダー対応を確認する

公開カタログは有効な名前を定義しますが、各プロバイダーのパーサーがすべてをマッピングするわけではありません。message.received と主要なアカウントイベントは広く対応し、受領通知、メッセージ編集、会話変更、グループ更新はプロバイダーごとに異なります。

コンシューマーがイベントへ依存する前に、プロバイダー別Webhookイベント差分を確認してください。有効な購読はフィルターであり、上流アカウントがそのイベントを生成する保証ではありません。

汎用収集基盤ではなく自動化を構築する場合は、n8nとWhatsAppの署名付きWebhookチュートリアルも参考になります。AIワークフローより先に検証と永続的な取り込みを置く理由を確認できます。

制限とトレードオフ

明示的なリストはノイズを減らして責任範囲を明確にしますが、新しい要件が生じるたびに設定更新が必要です。ワイルドカードは新しい公開イベントを取りこぼしにくい一方、より多くのタイプと将来の追加にコンシューマーが対応する必要があります。

UnifyPortには汎用的なRESTメッセージ履歴取得APIや、未達ペイロードの保証された再生機能はありません。本番のメッセージングアカウントを接続する前に受信エンドポイントを登録し、必要なイベントは到着時に保存してください。限定的なWhatsApp履歴同期は継続性の補助であり、独自イベントストアの代替ではありません。

UnifyPortは非公式インターフェースです。公式認証の経路や、文書化されたマトリクス外のプロバイダー固有機能が必要な場合は、各プラットフォームの公式APIを選択してください。

よくある質問

message.received と ["*"] のどちらを使うべきですか？

専用の受信箱ハンドラーなら message.received、公開標準イベントをすべて保存・配信する収集基盤なら ["*"] を使います。

message.received は受信メッセージだけですか？

いいえ。受信だけを扱う場合は data.message.direction が inbound か確認します。

プロバイダー内部イベントを購読できますか？

できません。subscribed_events が受け付けるのは公開標準名だけで、ワイルドカードも内部rawイベントを公開しません。

イベント名を間違えるとどうなりますか？

作成または更新リクエストが未知の名前を拒否します。一致しない設定が黙って保存されることはありません。

["*"] なら全プロバイダーですべてのイベントが届きますか？

いいえ。すべての公開標準タイプを選択しますが、実際の対応と上流の提供状況はプロバイダーにより異なります。

次のステップ

Webhookエンドポイント作成リファレンスを開き、3つのパターンから用途に合うものを選び、本番メッセージングアカウント接続前に受信先を登録してください。

参照資料

2026年8月19日に確認：

• UnifyPort — Create webhook endpoint
• UnifyPort — Standard event types and payload
• UnifyPort — Webhook delivery and signature verification
• UnifyPort — Quickstart