メインコンテンツまでスキップ

Webhook ゲートウェイ

Webhook ゲートウェイは、ChatWalaʻau を自前のチャット / API だけでなく 外部イベント （HTTP webhook）で駆動 できるようにします。Cron Scheduler や Pipeline と同じ形の、 ファイルベースで管理画面付きの小さなゲートウェイです。

最初の webhook source は Microsoft Graph で、Teams 会議のトランスクリプト を 自動で構造化要約に変換します。トランスクリプトが利用可能になると、ChatWalaʻau が会議を 解決し、トランスクリプトを取得し、LLM で JSON に要約し、結果をコーディング・ワークスペース へ書き出します。

本機能は オプトイン で既定では無効です。WEBHOOK_ENABLED=true で有効化します。

動作​

Microsoft Graph 変更通知
  -> POST /api/webhook/msgraph          (検証ハンドシェイク + 202 ACK)
  -> clientState・allowlist 検証、重複排除
  -> "teams-meeting" Pipeline ジョブを作成
  -> 会議解決 -> トランスクリプト取得 -> 要約 (LLM) -> JSON 書き出し
  -> done / failed   (Pipeline 画面で実行履歴とともに確認可能)

通知は「変更があった」ことだけを伝え、本文は ChatWalaʻau が後から Graph から取得します （プレーン通知＋フェッチ。証明書管理は不要）。

管理​

サイドバー footer の Webhooks アイコン（Declarative Agents アイコンの隣）から管理画面 を開きます。表示内容：

  • Sources — 各 webhook source と有効フラグ、受信件数。source の有効/無効を切替。
  • Receipts — source ごとの受信記録タイムライン。各通知は accepted / duplicate / rejected で表示され、生成された pipeline ジョブも分かります。
  • Microsoft Graph subscriptions — list / subscribe / renew / delete に加え、 Renew now（期限到来分を一括で即時更新）、Token health（Graph 資格情報・権限の 確認）、Validate（通知ハンドシェイクのセルフテスト）、手動 Fetch（主催者 ＋ meeting id / join URL を指定して要約を即時実行。subscription が無くてもテスト・バックフィルに 使える）。app-only アクセスは主催者スコープのため、主催者（AAD オブジェクト id または UPN）が 必須です。一覧にはローカル保存分に加え live（Graph 側）の subscription も表示されるため、 Graph にはあるがローカルに無い subscription（再デプロイや通知 URL 変更後など）が隠れません。

Subscribe で「既に存在します」と出たら​

Teams の議事録リソースはテナント内で アプリあたり subscription を 1 つ しか許しません。 既に subscription が存在する場合（過去のデプロイが作成したものを含む）、Subscribe は失敗 させず、既存 subscription を削除して再登録 する選択肢を提示します。削除されるのはその リソースの subscription だけで、無関係な subscription は残ります。

自動更新スケジュール​

Microsoft Graph パネルには managed の 自動更新スケジュール（実行間隔・次回実行）が表示され、 現在の subscription 向けにスケジュールを作り直す Create / Re-sync ボタンがあります。 CRON_ENABLED が無効の場合は、subscription が自動更新されない旨を警告します（Renew now で手動更新してください）。

同じ操作は manage_webhook エージェントツールと /api/webhooks/* REST API でも可能です。 mutating エンドポイントは認証が必要です（loopback は免除）。

Dedicated（ユーザー委任）レーン — サービスプリンシパル不要​

組織によっては app-only の Application 権限や Teams Application Access Policy を付与 できません。そうしたケース向けに、Microsoft Graph source 詳細には Dedicated fetch パネル もあります。サインインユーザーが 自分が主催した 会議を、自分自身のアカウントで device code サインイン（microsoft.com/devicelogin を開きコードを入力）して要約します。

  • Application 権限も Application Access Policy も不要。 Graph アクセスは User-Scoped （/me/onlineMeetings）で、自分の会議に自然に限定されます。
  • 新しい設定もクライアントシークレットも不要。 GRAPH_CLIENT_ID + GRAPH_TENANT_ID を public-client device-code サインインに再利用します。同じ app registration に delegated OnlineMeetingTranscript.Read.All + OnlineMeetings.Read の同意を追加し、「パブリッククラ イアントフローを許可」を有効化するだけです。
  • 何も保存しません。 サインイントークンはその 1 回の実行に使われるだけで破棄されます （リフレッシュトークンなし、ディスクにも書きません）。
  • organizer-scoped。 自分が主催した会議を要約できます。参加しただけの会議は取得できません （Microsoft Graph の制約）。主催者をまたいだ無人・イベント駆動の要約には上記の自動 （app-only）レーンを使ってください。

このレーンは手動・対話的（人によるサインインが必要）なので、portal からのみ実行でき、 manage_webhook エージェントツールからは実行できません。詳細なオペレーター手順は製品に同梱の 「Dedicated（ユーザー委任）Teams 会議セットアップ」ガイドにあります。

subscription は失効する — 更新を維持する​

Microsoft Graph の subscription には resource 依存の最大寿命があり、期限切れで配信が止まり ます。更新は Cron Scheduler に一本化 されています。subscription が 1 つ以上ある間、 ChatWalaʻau は managed・保護付きの Cron ジョブ（webhook カテゴリ）を維持し、期限前に subscription を自動更新します。このジョブは最初の Subscribe で作成され、最後の subscription を削除すると除去されます。Cron 画面に表示されますが、webhook 機能が所有する ため そこからは削除できません。Webhooks 画面の 自動更新スケジュール セクションにも表示され、 そこから Create / Re-sync できます。Cron ジョブのため、CRON_ENABLED が有効な間のみ 実行されます。無人運用では CRON_ENABLED=true を設定してください。そうでない場合は Webhooks 画面（Renew now / subscription 個別の Renew）やエージェントツールで手動更新します。 Graph の lifecycle イベント（reauthorizationRequired / subscriptionRemoved）はゲート ウェイが自動処理します。

セットアップ順序​

Microsoft Graph アクセスには、Teams ボット資格情報とは別の専用 app-only 資格情報 （GRAPH_*）を使います。推奨順序：

  1. Graph credentials — GRAPH_TENANT_ID / GRAPH_CLIENT_ID / GRAPH_CLIENT_SECRET を設定し、Token health で確認。
  2. Webhook listener — MSGRAPH_WEBHOOK_CLIENT_STATE、 MSGRAPH_WEBHOOK_NOTIFICATION_URL（公開・トンネル到達可能な URL）、 MSGRAPH_WEBHOOK_RESOURCE を設定し、Validate を実行。
  3. Teams pipeline — 既知の会議で手動 Fetch を実行し、要約パイプラインを end-to-end で確認。
  4. Teams delivery — Subscribe して実通知を流す。

Graph アプリ登録、トランスクリプト取得に必要な Teams Application Access Policy、 トンネル設定など、運用手順の詳細は製品同梱のセットアップガイドを参照してください。

セキュリティ​

公開 ingress（/api/webhook/{source}）は、API キー / セッション cookie の背後にない唯一の エンドポイントです（Microsoft Graph は API キー保持者ではないため）。保護は Graph 検証 ハンドシェイク、定数時間の clientState 比較、任意の source CIDR / resource allowlist、重複排除です。webhook 管理 API は他の書き込みエンドポイントと同様に認証され ます。

設定リファレンス​

変数既定説明
WEBHOOK_ENABLEDfalse機能全体のマスタースイッチ。
WEBHOOK_INGRESS_BASE_PATH/api/webhookベースパス。source は <base>/{source} に割当。
WEBHOOK_STORE_DIR.webhookssource 状態・受信記録・subscription の保存先。
WEBHOOK_RECEIPT_MAX_BYTES1048576受信記録本文の上限（0 = 無制限）。
MSGRAPH_WEBHOOK_CLIENT_STATE(空)Graph 通知検証用の共有シークレット。
MSGRAPH_WEBHOOK_NOTIFICATION_URL(空)subscribe 時に Graph へ渡す公開 URL。
MSGRAPH_WEBHOOK_RESOURCE(空)subscribe する Graph resource。
MSGRAPH_SUBSCRIPTION_RENEW_HOURS12更新間隔（resource 最大寿命より短いこと）。
MSGRAPH_WEBHOOK_ALLOWED_CIDRS(空)任意の source CIDR allowlist。
MSGRAPH_WEBHOOK_ALLOWED_RESOURCES(空)任意の resource allowlist。
GRAPH_TENANT_ID / GRAPH_CLIENT_ID / GRAPH_CLIENT_SECRET(空)Graph app-only 資格情報。
GRAPH_BASE_URLhttps://graph.microsoft.com/v1.0任意の Graph ベース URL 上書き。
TEAMS_MEETING_OUTPUT_DIRmeeting-summariesワークスペース内の出力サブディレクトリ。

会議要約のモデルは Model Offering Catalog の Model Settings -> Task model assignments （roles.meeting_summary、または chatwalaau models role set meeting_summary <offering-id>）で 指定します。未設定なら既定モデルを使います。専用の TEAMS_MEETING_SUMMARY_MODEL 変数は v0.109.0 で削除されました。

subscription 自動更新には別途 CRON_ENABLED=true が必要です。会議パイプラインは PIPELINE_ENABLED（既定で有効）を要し、CODING_WORKSPACE_DIR に書き出します。