Webhooks

    Webhooks

    概覽

    Webhooks 支援自訂整合工具應用程式訂閱 Workplace 中的事件並即時接收更新。當 Workplace 有所變更時，系統便會向所有已訂閱相關 Webhook 主題的自訂整合工具應用程式的回呼網址傳送 HTTPS POST 要求。

    這樣能讓應用程式確切知道變更何時發生，不需依賴連續或定期發出 Graph 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

    用戶在網頁或流動應用程式上使用密碼或 SSO 登入 Workplace。

    log_out

    用戶在網頁或流動應用程式上使用密碼或 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

    用戶透過「設定」分頁停用雙重驗證。此事件不會記錄用戶停用特定手機雙重驗證的時間，而是表示此功能已停用。