Webhooks - 文件 - Meta for Developers

Webhooks

總覽

Webhooks 讓自訂整合應用程式能夠訂閱 Workplace 中的事件並即時接收更新。當 Workplace 中發生變更時，系統會將 HTTPS POST 要求傳送到訂閱相關 Webhook 主題之每個自訂整合應用程式的回呼網址。

如此可讓應用程式更有效率，因其能夠確切知道變更何時發生，且不需依賴連續或甚至定期的圖形 API 要求來取得最新內容。

Workplace 專用 Webhook 支援是由支援 Facebook 專用 Webhooks 的相同架構所提供。

訂閱 Webhook 主題

「編輯自訂整合」對話方塊為可供 Workplace 上的應用程式使用的每個 Webhook 主題提供頁籤。

「編輯自訂整合」對話方塊中的 Webhooks 頁籤

若要對指定主題新增 Webhook 訂閱，請提供回呼網址和驗證權杖，然後選擇應用程式將提供之功能所需的訂閱欄位。

每個 Webhook 主題只能訂閱一個網址，但可以對多個主題使用同一網址。

處理驗證要求

當您新增訂閱或修改現有訂閱時，Facebook 伺服器將向您的回呼網址發出 GET 要求，以驗證回呼伺服器的有效性。

系統會將查詢字串與下列參數一起附加到此網址：

hub.mode - 此參數會傳遞「subscribe」字串
hub.challenge - 隨機字串
hub.verify_token - 建立訂閱時指定的 verify_token 值

當您在回呼網址上收到 HTTP GET 要求時，可以使用 verify_token 參數驗證該要求是否來自 Facebook 伺服器。

Webhook 安全性

所有針對開發人員定義回呼網址的 Webhook 呼叫都是透過 HTTPS 進行，可確保 Webhook 承載的傳輸層級安全性。

為了提供額外的安全性，每個 POST 承載中都包含 HTTP 標頭 X-Hub-Signature-256，您應用它來驗證承載是否來自 Facebook 伺服器。

有關此行為的完整詳細資訊，請參閱 Facebook Webhook 架構文件。

Webhook 主題

系統會將 Workplace 的動態依主題分組。每個主題都有許多欄位，這些欄位會對應到指定主題的事件。應用程式可以訂閱每個主題的 Webhook 更新，以及每個主題內的特定欄位。

Workplace 目前提供下列主題和社團的 Webhooks：

粉絲專頁

如需詳細資訊，請參閱粉絲專頁主題參考文件。

訂閱欄位	行為
`mention`	當社團中提及自訂整合粉絲專頁（Bot）時觸發。
`messages`	在 Work Chat 中向自訂整合粉絲專頁（Bot）傳送訊息時觸發。
`message_deliveries`	當傳遞自訂整合粉絲專頁（Bot）所傳送的訊息時觸發。
`messaging_postbacks`	在 Work Chat 中按下回傳按鈕時觸發。
`message_reads`	當收件者讀取來自自訂整合粉絲專頁（Bot）的訊息時觸發。

社團

如需詳細資訊，請參閱社團主題參考文件。

訂閱欄位	行為
`posts`	當社團中新增、更新或刪除貼文時觸發。
`comments`	在社團中，每當加入、更新或刪除貼文的新留言時觸發。
`membership`	當社團成員變更時觸發。

用戶

如需詳細資訊，請參閱用戶主題參考文件。

訂閱欄位	行為
`status`	當用戶在自己的個人檔案發佈或編輯動態更新時觸發。
`events`	每當用戶建立、接受或婉拒事件時觸發。
`message_sends`	每當用戶傳送 Workplace Chat 訊息時觸發。

連結

如需詳細資訊，請參閱驗證預覽文件。

訂閱欄位	行為
`preview`	當 Workplace 需要擷取有關網址的資訊時觸發。
`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`	用戶已從「設定」頁籤停用雙重驗證。這麼做並不會擷取停用特定手機之雙重驗證的用戶，而是指示該功能已停用。