Webhooks - ドキュメンテーション

概要

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

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

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

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

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

[カスタム統合を編集]ダイアログのWebhooksタブ

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

Webhookトピックごとに1つのURLしかサブスクリプション登録できませんが、複数のトピックで同じURLを使うこともできます。

確認リクエストの処理

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

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

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

コールバックURLでHTTP GETリクエストを受信したら、verify_tokenパラメーターを使用して、リクエストがFacebookサーバーからのものであることを確認できます。

Webhookのセキュリティ

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

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

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

Webhookのトピック

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

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

ページ

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

サブスクリプションフィールド	動作
`mention`	カスタム統合ページ(ボット)がグループ内でメンションされたときにトリガーされます。
`messages`	カスタム統合ページ(ボット)にWork Chatでメッセージが送信されたときにトリガーされます。
`message_deliveries`	カスタム統合ページ(ボット)から送信されたメッセージが配信されたときにトリガーされます。
`messaging_postbacks`	Work Chatでポストバックボタンが押されたときにトリガーされます。
`message_reads`	カスタム統合ページ(ボット)からのメッセージが受信者に読まれたときにトリガーされます。

グループ

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

サブスクリプションフィールド	動作
`posts`	グループで投稿が追加、更新、削除されたときにトリガーされます。
`comments`	グループの投稿に新しいコメントが追加されたり、コメントが更新または削除されたりするたびにトリガーされます。
`membership`	グループのメンバーが変更されたときにトリガーされます。

ユーザー

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

サブスクリプションフィールド	動作
`status`	ユーザーが投稿をしたり、自分のプロフィールの近況アップデートを編集したりしたときにトリガーされます。
`events`	ユーザーがイベントを作成、承諾、拒否するたびにトリガーされます。
`message_sends`	ユーザーがWorkplace Chatメッセージを送信するたびにトリガーされます。

リンク

詳しくは、アクセス認証プレビューのドキュメントをご覧ください。

サブスクリプションフィールド	動作
`preview`	WorkplaceがURLに関する情報を取得する必要があるときにトリガーされます。
`collection`	投稿ツールの階層ナビゲーションをサポートする許可リストにあるアプリにだけ関係します。

セキュリティ

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

`sessions`

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

イベント動作

イベント	動作
`log_in`	ユーザーが、wwwまたはモバイルアプリのいずれかで、パスワードまたはSSOを使用してWorkplaceにログインした。
`log_out`	ユーザーが、wwwまたはモバイルアプリのいずれかで、パスワードまたはSSOを使用してWorkplaceからログアウトした。管理者による強制ログアウトは含まれません(`admin_force_log_out`を参照)

log_in

ユーザーが、wwwまたはモバイルアプリのいずれかで、パスワードまたはSSOを使用してWorkplaceにログインした。

log_out

ユーザーが、wwwまたはモバイルアプリのいずれかで、パスワードまたはSSOを使用してWorkplaceからログアウトした。

管理者による強制ログアウトは含まれません(admin_force_log_outを参照)

`passwords`

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

イベント	動作
`password_change`	パスワード再設定を実行した結果、またはアカウント設定から、ユーザーのパスワードが変更された。
`password_reset_request`	ユーザーのパスワード再設定フローが開始され、ユーザーのメールアドレスにコードが送信された。
`password_reset_wrong_code`	ユーザーが誤ったパスワードリセットリカバリーコードを入力した。
`password_reset_success`	ユーザーのパスワード再設定フローが正常に完了した。

`admin_activity`

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

イベント	動作
`admin_set_to_unclaimed`	管理者が管理者用パネルから、またはアカウント管理APIを介して、ユーザーのアカウント状態を未取得に設定した。
`admin_force_log_out`	管理者が管理者用パネルで、ユーザーをすべてのデバイスから強制的にログアウトさせた。
`admin_deactivate`	管理者が管理者用パネルから、またはアカウント管理APIを介して、アカウントを停止した。
`admin_activate_account`	管理者が管理者用パネルから、またはアカウント管理APIを介して、アカウントを有効にした。
`force_password_reset`	管理者が管理者用パネルで、ユーザーのパスワードを強制的にリセットした。
`admin_create_account`	管理者が管理者用パネルでアカウントを作成した。

`two_factor`

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

イベント	動作
`two_factor_enable`	ユーザーが[設定]タブから二段階認証を有効にした。これは、誰かが特定の電話番号を確認したときに取得されるのではなく、機能が有効になったことを示します。
`two_factor_disable`	ユーザーが[設定]タブから二段階認証を無効にした。これは、誰かが特定の電話番号の二段階認証を無効にしたときに取得されるのではなく、機能が無効になったことを示します。