Webhooks

概要

Webhooksは、カスタム統合アプリでWorkplaceのイベントをサブスクリプション登録し、リアルタイムでアップデートを受信できるようにします。Workplaceで変更が発生した場合、関連するWebhookトピックをサブスクリプション登録している各カスタム統合アプリのコールバックURLに対し、HTTPS POSTリクエストが送信されます。

こうすることにより、変更が行われた時点でアプリでその変更を把握でき、最新のコンテンツを取得するために継続的または定期的にグラフAPIリクエストを行う必要がなくなるので、アプリがより効率化されます。

WorkplaceのWebhookサポートは、グラフAPI用Webhooksと同じフレームワークによって提供されています。

Webhookトピックのサブスクリプション登録

[カスタム統合を編集]ダイアログには、Workplaceのアプリで利用可能な各Webhookトピックのタブが用意されています。

[カスタム統合を編集]ダイアログのWebhooksセクション

特定のトピックに新しいWebhookサブスクリプションを追加するには、[コールバックURL]と[検証トークン]を指定してから、アプリが提供する機能に必要な[サブスクリプションフィールド]を選択します。

確認リクエストの処理

新しいサブスクリプションを追加したり、既存のサブスクリプションを修正したりすると、コールバックサーバーの有効性を確認するために、MetaサーバーからコールバックURLに対してGETリクエストが実行されます。

コールバックURLには、次のパラメーターを使用してクエリ文字列が追加されます。

• hub.mode - このパラメーターでは文字列「subscribe」が渡されます
• hub.challenge - ランダムな文字列
• hub.verify_token - サブスクリプションを作成したときに指定したverify_token値

エンドポイントは確認リクエストを受け取ると、必ず次のことを行います。

• hub.verify_token値が、Webbook設定時に[トークンの確認]フィールドで設定した文字列と一致していることを確認します。
• hub.challenge値で応答します。

Webhookのセキュリティ

開発者が定義したコールバックURLへのWebhook呼び出しはすべてHTTPSを介して行われ、Webhookペイロードのトランスポートレベルのセキュリティが確保されます。

追加のセキュリティを提供するために、各POSTペイロードにはHTTPヘッダーX-Hub-Signature-256が含まれており、これを使用することによって、ペイロードがMetaサーバーからのものであることを確認できます。

この動作について、詳しくはWebhookフレームワークに関するドキュメントをご覧ください。

開発者が定義したコールバックURLへのWebhook呼び出しはすべてHTTPSを介して行われ、Webhookペイロードのトランスポートレベルのセキュリティが確保されます。

API呼び出しを使用したWebhooksへのサブスクリプション登録

Webhookサブスクリプションを読み込んだり変更したりするためのAPI呼び出しには、通常のカスタム統合トークンではなく、アプリトークンを使用する必要があります。アプリトークンは、アプリID、「|」記号、app secretを連結して生成できます。

以下はその例です。

現在のWebhookサブスクリプション登録を取得する(アプリトークンを使用)

GET graph.facebook.com
  /{app-id}/subscriptions
    &access_token={your_app_token}

新しいWebhookサブスクリプション登録を追加する(アプリトークンを使用)

POST graph.facebook.com
  /{app-id}/subscriptions
    ?object=page
    &fields=mention,messages
    &callback_url={your-url}
    &verify_token={your-verify-token}
    &access_token={your_app_token}

ページとアプリのサブスクリプション登録のトラブルシューティング

Webhooksを期待通りに受信できない場合は、ページとアプリの間のサブスクリプション登録が正しく設定されているかを確認してください。これは自動で設定されますが、失敗する場合もあります。例えば、Webhookの配信に長期間失敗した場合、このサブスクリプション登録は削除されることがあります。サードパーティアプリの場合は、アプリダッシュボードにアラートが表示されます。

このサブスクリプション登録を確認するには、以下のAPI呼び出しを使用します。

現在のアプリ/ページのサブスクリプション登録を取得する(ページトークンを使用)

GET graph.facebook.com
  /me/subscribed_apps?access_token={your_page_token}

このサブスクリプション登録を再作成するには、以下のAPI呼び出しを使用します。

現在のアプリ/ページのサブスクリプション登録を再作成する(ページトークンを使用)

POST graph.facebook.com
  /me/subscribed_apps?access_token={your_page_token}
	{"subscribed_fields": ["messages"...]}

Webhookのトピック

Workplaceでのアクティビティは、いくつかのトピックにグループ化されます。各トピックには、特定のトピックのイベントに対応する多数のフィールドがあります。アプリは、各トピックのWebhookの更新や、各トピック内の特定のフィールドについてサブスクリプション登録することができます。

現在、Workplaceでは次のトピックやグループのWebhooksが提供されています。

ページ

詳しくはページトピックのリファレンスドキュメントをご覧ください。

グループ

詳しくはグループトピックのリファレンスドキュメントをご覧ください。

ユーザー

詳しくは、ユーザートピックのリファレンスドキュメントをご覧ください。

セキュリティ

詳しくは、セキュリティトピックのリファレンスドキュメントをご覧ください。

admin_activity

管理者がWorkplaceコミュニティに追加された、またはそこから削除されたときにトリガーされるイベント

compromised_credentials

コミュニティ内の一部のユーザーアカウントのWorkplaceパスワードにリスクがあると考えられるときにトリガーされるイベント。

files

Workplaceのファイルアクティビティでトリガーされるイベント。

groups

社員がWorkplaceの会社間グループを作成、または会社間グループに参加したときにトリガーされるイベント。

integrations

管理者が統合のプロパティを作成または変更したときにトリガーされるイベント。

invites

社員がセルフ招待経由でWorkplaceに参加したときに発生するイベント。

passwords

社員がパスワードを変更したり、パスワードのリセットをリクエストしたりしたときにトリガーされるイベント。

sessions

社員がWorkplaceでログインまたはログアウトを実行したときにトリガーされるイベント。

two_factor

社員が二段階認証を有効または無効にしたときにトリガーされるイベント。

reseller_events

リセラーに関連するイベント。

リンク

詳しくは、リンクトピックのリファレンスドキュメントをご覧ください

情報ライブラリ

さらに詳しくは、情報ライブラリカテゴリグラフAPIのドキュメントをご覧ください。