Microsoft Graph Webhook リスナー

まるでこう考えてみてください。スマホが冷蔵庫を常にチェックして牛乳が無くなっていないか確認する代わりに、冷蔵庫の方が牛乳が無くなった瞬間にテキストを送ってくれる、と。それがまさにウェブフックリスナーの仕組みです。信号を待って、自動的に反応するんです。

---

これは実際に何をするのか？

Microsoft Graph Webhook Listener は、Hermes Agent の機能の一つで、Microsoft 365 (M365) から Hermes へ「何かが起こった」ことを知らせてもらうためのものです。例えば、Teams の会議が終わった、新しいチャットメッセージが届いた、カレンダーの予定が更新された、といった具合です。

これは、話しかけるチャットボットではありません。どちらかというと、Microsoft Graph からの「変更通知」を静かに待ち受け、会議の文字起こしを取得して Teams に要約を投稿するといった、役に立つ処理をパイプラインで実行する、無言のアシスタントのようなものです。

---

始める前に必要なもの

必要なものは次の3つです。

1. Microsoft Graph アプリの資格情報 — Microsoft の Azure ポータルでアプリを登録します。
2. パブリックな HTTPS URL — Microsoft Graph は localhost を呼び出しません。テストには開発トンネルで十分ですが、本番環境では実際のドメインが最適です。
3. 強力なシークレット — これは clientState の値で、通知が本当に Microsoft からのものであることを検証するために使われます。

シークレットは次のコマンドで生成します。

openssl rand -hex 32

そして、~/.hermes/.env に次のように記述します。

MSGRAPH_WEBHOOK_CLIENT_STATE=your-generated-secret-here

---

クイックスタート設定

リスナーを有効にする最も簡単な方法は、最小限の設定ファイル（~/.hermes/config.yaml）を使うことです。

platforms:
  msgraph_webhook:
    enabled: true
    extra:
      host: 127.0.0.1
      port: 8646
      client_state: "replace-with-a-strong-secret"
      accepted_resources:
        - "communications/onlineMeetings"

または、~/.hermes/.env で環境変数を使う方法もあります（起動時に自動的にマージされます）。

MSGRAPH_WEBHOOK_ENABLED=true
MSGRAPH_WEBHOOK_PORT=8646
MSGRAPH_WEBHOOK_CLIENT_STATE=your-generated-secret-here
MSGRAPH_WEBHOOK_ACCEPTED_RESOURCES=communications/onlineMeetings

注意: バインドホストは設定ファイルの extra.host からのみ読み取られます。MSGRAPH_WEBHOOK_HOST のような環境変数による上書きはありません。

---

リスナーの起動

次のコマンドでゲートウェイを起動します。

hermes gateway run

起動すると、リスナーは以下のエンドポイントを公開します。

• POST /msgraph/webhook — Microsoft Graph からの変更通知を受け取ります
• GET /msgraph/webhook?validationToken=... — サブスクリプション検証のハンドシェイクを処理します
• GET /health — 受け入れ済み/重複通知のカウンターを備えた準備完了プローブです

---

パブリック公開

Microsoft Graph がリスナーに到達できるようにするには、リスナーを公開する必要があります。リバースプロキシ、開発トンネル、またはイングレスを使用します。Graph サブスクリプション用の通知 URL は次のようになります。

https://ops.example.com/msgraph/webhook

---

設定チートシート

すべての設定は platforms.msgraph_webhook.extra の下にあります。

設定	デフォルト	説明
host	未設定（全インターフェース）	バインドアドレス。開発トンネルには 127.0.0.1 を使用します。
port	8646	リッスンするポート。
webhook_path	/msgraph/webhook	Graph が POST するパス。
health_path	/health	準備完了エンドポイント。
client_state	—	共有シークレット。安全に比較されます。
accepted_resources	[]（すべて受け入れる）	Graph リソースパスの許可リスト。ワイルドカードには * を使用します。

---

まとめと実用的なヒント

Microsoft Graph Webhook Listener は、M365 のイベントと Hermes のアクションを結ぶ橋渡し役です。複雑なものではなく、信号を待ってワークフローを起動する、ただのリスナーです。

実用的なヒント: まずは accepted_resources を1つのリソース（例：communications/onlineMeetings）に限定して、シンプルに始めましょう。通知が流れるのを確認できたら、リストを拡張します。そして、常に適切に生成された client_state を使用してください。これは Microsoft とのセキュリティハンドシェイクです。

---