SharePoint と M365 向けに信頼性の高い Microsoft Graph Webhook を構築する方法

By Mirko Peters · 2025-11-16

セキュアな検証、自動化された更新、堅牢な通知配信を備えた、SharePoint と M365 向けの信頼性の高い Microsoft Graph Webhook を構築します。

Automatically translated with AI from the original post. Read the English original

SharePoint と M365 向けに信頼性の高い Microsoft Graph Webhook を構築するのは、経験豊富な開発者にとっても難しい作業になることがあります。エンドポイントが検証トークンを返さない、または200 OK ステータスで応答しない場合、検証に失敗する問題が発生することがあります。よくある問題として、ファイアウォールによるエンドポイントのブロック、ネットワークの設定ミス、ミドルウェアの干渉などがあります。サービスが検証要求を受信できない場合や、エンドポイントがパブリックにアクセスできない場合には、再試行の取りこぼしやサブスクリプションの期限切れがしばしば発生します。本記事では、こうした落とし穴を回避し、堅牢でセキュアな通知パイプラインを構築する方法を、実践的なチェックリストとベストプラクティスとともに解説します。

重要なポイント

• Microsoft Graph Webhook は、定期的なポーリングを必要とせず、Microsoft 365 の変更についてリアルタイムに通知を提供します。

• Webhook のエンドポイントは、セキュリティと信頼性を確保するために、パブリックにアクセスでき、HTTPS を使用するようにしてください。

• 検証要求には迅速に応答し、検証トークンを返してください。これにより、Webhook のサブスクリプションを正常に有効化できます。

• 通知配信の失敗に対処し、データの損失を防ぐために、堅牢な再試行とバックオフの戦略を実装してください。

• サブスクリプションの更新を自動化し、Webhook パイプラインを監視して、継続的かつ信頼性の高い通知を確保してください。

Microsoft Graph Webhook の基礎

Microsoft Graph Webhook とは

Webhook は、ソースシステムでイベントが発生したときにトリガーされ、通常はデータのペイロードを伴って送信先システムに送信される HTTP リクエストです。Webhook は自動化されたものであり、言い換えると、ソースシステムでイベントが発火すると自動的に送信されます。

Microsoft Graph Webhook を使用すると、Microsoft 365 環境内の変更について、リアルタイムに通知を受け取ることができます。つまり、Microsoft Graph に対して更新の有無を絶えず問い合わせる必要がありません。代わりに、重要なことが発生した時点で、アプリケーションに通知が届きます。これにより、Microsoft Graph から取得できるデータを最新の状態に保ち、同期できます。また、最新の変更を確認するために Microsoft Graph へ頻繁に要求を送信する、ポーリング用のインフラストラクチャも不要になります。

次のような、さまざまな種類のイベントについて通知を設定できます。

• メッセージ

• 予定

• 連絡先

• ユーザー

• グループ

• 会話

• OneDrive のファイル

• アラート

たとえば、組織に新しいユーザーが参加したときに、サードパーティの工数管理システムにアカウントを自動的に作成するといったケースが考えられます。また、SharePoint のドキュメント ライブラリや OneDrive のフォルダーに誰かが新しいファイルを追加したときに、経費精算などのコンテンツ処理をトリガーすることもできます。

信頼性が重要な理由

Microsoft Graph Webhook は、SharePoint や Microsoft 365 との連携を、応答性が高く最新の状態に保つうえで重要な役割を果たします。Webhook パイプラインが確実に動作していれば、アプリケーションは変更にリアルタイムで対応できます。ユーザーは常に最新のデータを確認でき、体験が向上するとともに、古い情報が使われるリスクも低減されます。

ただし、信頼性の問題は深刻な障害につながる可能性があります。

• 適切に対処されなければ、Webhook の失敗はアプリケーションの機能を損なう可能性があります。

• トラフィックの急増はサーバーに過負荷をかけ、ダウンタイムや Webhook リクエストの消失につながる可能性があります。

• 再送の仕組みがない場合、Webhook を正しく処理できないことで、データの損失や不整合が生じるおそれがあります。

• 保護されていない Webhook の URL は悪用され、攻撃者に不正なデータを送信されるおそれがあります。

堅牢なソリューションを構築するには、変更を効率的に追跡するために、Webhook とデルタクエリを組み合わせることをお勧めします。また、サブスクリプションを定期的に確認し、更新するプロセスも設定する必要があります。頻繁に更新されるリソースについては、リクエストをバッチ処理することで負荷を管理しやすくなります。

Webhook の設定と検証

SharePoint と Microsoft 365 で Microsoft Graph Webhooks を設定するには、いくつかの重要な手順があります。Webhook の登録、検証要求の処理、エンドポイントの保護が必要です。各手順は、通知の仕組みが確実かつ安全に動作するために欠かせません。

Microsoft Graph Webhooks の登録

まず Webhook サブスクリプションを作成します。この処理により、アプリケーションは Microsoft 365 リソースの変更に関する通知を受け取れるようになります。Webhook を登録するには、次の手順に従ってください。

1. HTTPS を使用する公開アクセス可能なエンドポイントを作成します。このエンドポイントが Microsoft Graph からの通知を受け取ります。

2. Microsoft Graph の /subscriptions エンドポイントに POST 要求を送信します。

3. サブスクリプション要求では、次の項目を指定します。

   • changeType: 追跡する変更の種類です。「created」「updated」「deleted」などを指定します。

   • notificationUrl: Webhook エンドポイントの URL です。

   • resource: 監視するリソースです。「/users」「/drive/root」などを指定します。

   • expirationDateTime: サブスクリプションの有効期限となる日時です。

   • clientState などの省略可能なプロパティを使うと、通知の送信元を検証しやすくなります。

サブスクリプション要求の例:

POST https://graph.microsoft.com/v1.0/subscriptions
Authorization: bearer eyJ0eXAiOiJ[..]
Content-Type: application/json

{
  "changeType": "updated",
  "clientState": "SecretClientState",
  "notificationUrl": "https://yourdomain.com/api/notifications",
  "resource": "/users",
  "expirationDateTime": "2024-05-01T00:00:00.0000000+00:00"
}

エンドポイントは公開アクセス可能で、HTTPS で保護されている必要があります。Microsoft Graph は、サブスクリプションを完了する前に通知 URL を検証します。通知を受け取り続けるには、サブスクリプションを定期的に更新する必要があります。また、通知を取りこぼさないよう、エンドポイントは迅速かつ一貫した HTTP 応答を返すべきです。

登録に必要なフィールドの概要は次のとおりです:

検証要求の処理

Webhook を登録すると、Microsoft Graph からエンドポイントに検証要求が送信されます。サブスクリプションの手続きを完了するには、正しく応答する必要があります。エンドポイントが validationToken クエリパラメーターを含む GET 要求を受け取ったら、そのトークンをプレーンテキストとして応答本文に返し、200 OK ステータスを返します。

• validationToken を返さないと検証エラーが発生します。Microsoft Graph はエンドポイントを確認できないため、通知を受け取れなくなります。

• clientState プロパティを使用して、要求がご自身のサブスクリプションからのものかを確認してください。

• validationToken は、必ず 10 秒以内にプレーンテキストとして応答本文に返してください。

💡 ヒント: 検証要求に素早く正確に応答すると、Webhook サブスクリプションを問題なく有効化できます。

HTTPS とエンドポイントのセキュリティ

Webhook エンドポイントの保護は欠かせません。Microsoft Graph Webhooks では、通信中の機密データを保護するために HTTPS 暗号化が必要です。受信要求は、共有秘密鍵で作成された署名を確認して検証してください。コールバック URL には複雑でランダムに生成されたパスを使用すると、推測されにくくなります。

• Microsoft Graph API のエンドポイントに対して IP ホワイトリストを追加します。

• 要求ヘッダーに認証トークンを含めます。

• API の使用状況を監視し、異常なパターンや急増がないかを検出します。

• Microsoft Graph と Outlook API へのアクセスを制限します。許可された担当者のみがアクセスできるようにし、多要素認証を必ず適用してください。

• 行動分析と機械学習を使用して脅威を特定する高度なエンドポイントセキュリティソリューションを導入します。

• 定期的にセキュリティ監査を実施し、脆弱性を発見して修正します。

Webhook のコールバックはそれぞれ、受信 HTTPS リクエストの Authentication ヘッダーに署名付きの JSON Web Token (JWT) を含みます。標準的な OpenID Connect の JWT 検証手法を使用して、トークンの整合性を確認できます。

すべての Webhook エンドポイントで HTTPS を使用する必要があります。この要件はデータを保護し、Microsoft のセキュリティ標準への準拠を確実にします。エンドポイントを保護することで、不正アクセスや攻撃の防止に役立ちます。

これらの手順に従うことで、SharePoint と M365 向けの信頼性が高く安全な Microsoft Graph Webhooks のパイプラインを構築できます。アプリケーションは、通知を迅速かつ安全に受け取れるようになります。

通知の処理とセキュリティ保護

Webhook エンドポイントを設定したら、受信した通知を安全かつ確実に処理する必要があります。この手順により、アプリケーションが有効なリクエストのみを受け入れ、Microsoft Graph Webhooks からの重要な更新を取りこぼさないようになります。

JWT トークンの認証と検証

Microsoft Graph からのすべての通知には、Authorization ヘッダーに JSON Web Token (JWT) が含まれています。ペイロードを処理する前に、必ずこのトークンを検証してください。適切な JWT 検証により、不正または改ざんされたリクエストからシステムを保護できます。

JWT トークンを認証および検証するには、次の手順に従ってください:

1. トークンの有効期限が切れていないことを確認します。トークンには有効期限が含まれており、期限を過ぎたトークンは拒否する必要があります。

2. トークンを発行したのが Microsoft identity platform であることを確認します。署名を検証して、トークンが改ざんされていないことを確かめます。

3. トークン内の "audience" クレームが、アプリケーションの ID と一致することを確認します。この手順により、そのトークンが自分のアプリ宛てに発行されたものであることを確認できます。

4. azp (authorized party) プロパティが、アプリケーションの想定値と一致することを確認します。

ヒント: JWT の検証には、必ず信頼できるライブラリを使用してください。これらのライブラリは一般的な誤りを避けるのに役立ち、アプリケーションを安全に保ちます。

JWT トークンを扱う際は、次の一般的なセキュリティ脆弱性にも注意してください:

• JWT の署名を検証しないと、攻撃者がトークンの内容を検知されずに変更できてしまう可能性があります。

• JWT の処理で 'none' アルゴリズムを使用すると、攻撃者が署名チェックを回避できてしまいます。

• 署名シークレットが弱いと、攻撃者が有効なトークンを偽造しやすくなります。

• 攻撃者が JOSE ヘッダーに特定のパラメーターを挿入し、システムによる JWT の処理方法を操作する場合があります。

これらの手順と予防策に従うことで、正当な通知だけがアプリケーションに届くようになります。

ペイロードの処理

通知を認証したら、ペイロードを安全に処理する必要があります。通知ペイロードには、Webhook をトリガーしたイベントに関する情報が含まれています。データの整合性を維持し、セキュリティ上の問題を防ぐために、次の対応を行ってください:

• 必要なフィールドがすべて含まれていることを確認します。不足しているフィールドは、エラーや処理の不完全さの原因になります。

• テキストフィールドは、画面に表示する前やデータベースに保存する前に、必ずサニタイズしてください。この手順により、インジェクション攻撃やデータの破損を防げます。

• スキーマ検証を使用して、ペイロードが想定される構造に一致することを確認します。スキーマ検証は、予期しない変更や不正な形式のデータを検出するのに役立ちます。

• API のバージョン変更に備えてコードを準備しておきます。柔軟な解析により、Microsoft がペイロード形式を更新しても、アプリケーションが引き続き動作します。

注: ペイロードの検証とサニタイズにより、不正な形式のデータやセキュリティの脅威からシステムを保護できます。

再試行とバックオフ ロジックの実装

ネットワークの問題や一時的な停止により、通知の配信が失敗することがあります。データの損失を防ぐには、堅牢な再試行およびバックオフの戦略が必要です。Microsoft は、再試行を管理するために指数バックオフと構造化されたキューの使用を推奨しています。

一般的な再試行およびバックオフの仕組みをまとめた表は次のとおりです:

再試行とバックオフのロジックを適切に実装しない場合、通知を失ったり、データの不整合が発生したりするリスクがあります。要求の失敗やレート制限によって、重要な更新を受け取れなくなることもあります。指数バックオフを使うと、スロットルされた要求を管理でき、システムや Microsoft Graph Webhooks への過負荷を防げます。

🛡️ ベストプラクティス: 再試行回数を必ず追跡し、数回再試行した後も失敗するメッセージは破棄キューへ移動してください。この方法なら、データを失うことなく、継続的な問題を調査して解決できます。

JWT トークンの認証、ペイロードの検証、信頼性の高い再試行ロジックを組み合わせることで、安全で回復力のある通知パイプラインを構築できます。これらの手順により、Microsoft Graph Webhooks からのすべての通知を安全かつ効率的に処理できます。

サブスクリプションの管理と変更の追跡

サブスクリプションの更新の自動化

通知の取りこぼしを防ぐため、webhook サブスクリプションを有効な状態に保つ必要があります。Microsoft Graph のサブスクリプションは、一定期間が経過すると期限切れになります。更新しないと、アプリケーションは更新情報を受け取れなくなります。更新は、次のようないくつかの方法で自動化できます。

• 各サブスクリプションの有効期限を更新するには、HTTP PATCH 要求を送信します。

• これらの PATCH 要求は毎日実行されるようスケジュールします。これにより、サブスクリプションが常に有効な状態に保たれ、予期しない期限切れを防げます。

• すべてのサブスクリプションの有効期限のタイムスタンプを追跡します。期限が近いサブスクリプションは更新してください。

• サブスクリプションが期限切れになった場合は、通知の流れを復旧するために直ちに新しいサブスクリプションを作成します。

ヒント: 更新を自動化すると手作業が減り、システムが Microsoft Graph と常に接続された状態を維持できます。

監視とアラート

webhook パイプラインの状態を必ず監視してください。サブスクリプションの更新に失敗した場合や、エンドポイントが応答しなくなった場合に通知されるよう、アラートを設定します。受信した通知と更新の試行を追跡するには、ログを利用します。これにより、ユーザーに影響が出る前に問題を発見できます。

• サブスクリプションの状態と有効期限を監視します。

• 更新の失敗や通知の取りこぼしに対するアラートを設定します。

• トラブルシューティングのため、すべての webhook イベントとエラーをログに記録します。

🛎️ 事前の監視により問題を迅速に解決でき、連携の信頼性を維持できます。

変更の追跡にデルタ クエリを使用する

デルタ クエリを使うと、変更を効率的に追跡できます。SharePoint や M365 のリソースに対して利用できます。新規または更新されたデータのみを取得できるため、頻繁なポーリングを減らし、スロットルのリスクも抑えられます。

• デルタ クエリを使うと、毎回すべてのデータをダウンロードせずに、アプリケーションで変更を追跡できます。

• SharePoint や M365 との相性も良く、変更があった場合にのみ通知を送信します。

• デルタ クエリを使うことで、帯域幅を節約し、パフォーマンスを向上できます。

ただし、デルタ クエリには次のような制限があります。

注: これらの制限に対応し、変更を正確に追跡できるよう、デルタ クエリの実装は必ずテストしてください。

更新の自動化、パイプラインの監視、デルタ クエリの活用により、SharePoint や M365 向けの信頼性が高く効率的な webhook システムを構築できます。

信頼性の高い Microsoft Graph Webhook は、明確なプロセスに沿って構築できます。まず、サブスクリプションの作成とデルタ クエリの利用によって変更を追跡します。更新は自動化し、パイプラインに問題がないか監視してください。各段階で、検証、セキュリティ、回復性を優先しましょう。本番環境への準備を整えるには、こちらのチェックリストを確認してください:

• ドキュメントを最新の状態に保ち、サポート チームへの情報共有を怠らないようにしてください。

• サブスクリプションの状態を定期的にチェックするスケジュールを設定してください。

• CI パイプラインのセキュリティ スキャンを使用し、監査証跡を維持してください。

これらのベスト プラクティスを適用して、SharePoint と M365 の統合が確実に機能し続けるようにしてください。

よくある質問

期限切れの Microsoft Graph Webhook サブスクリプションは、どのように更新しますか?

Microsoft Graph の /subscriptions/{id} エンドポイントに PATCH 要求を送信し、expirationDateTime フィールドを更新します。この処理は毎日実行されるようにスケジュールしてください。これによりサブスクリプションが有効な状態に保たれ、通知の取りこぼしを防げます。

Webhook エンドポイントが検証に失敗した場合は、どうすればよいですか?

エンドポイントが応答本文に validationToken をプレーン テキストとして返しているか確認してください。応答は 200 OK ステータスで返します。エンドポイントがインターネットからアクセス可能で、HTTPS を使用していることも確認してください。

Webhook エンドポイントはどのように保護できますか?

すべてのエンドポイントで HTTPS を使用してください。すべての要求で JWT トークンを検証します。認証と IP ホワイトリストによってアクセスを制限します。不審なアクティビティを監視し、セキュリティ設定を定期的に監査してください。

Webhook と組み合わせてデルタ クエリを使う必要があるのはなぜですか?

デルタ クエリを使うと、新規または変更されたデータだけを追跡できます。これにより帯域幅の使用量が減り、パフォーマンスが向上します。毎回すべてのデータをダウンロードする必要がなくなるため、統合がより高速で効率的になります。

失敗した Webhook 通知を処理する最善の方法は何ですか?

指数バックオフによる再試行ロジックを実装してください。ヘッダーまたはキューを使って再試行回数を追跡します。数回の再試行後も失敗したメッセージは、破棄キューに移動します。データ損失を防ぐため、これらの失敗は調査してください。