Webhooks

總覽

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

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

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

訂閱 Webhook 主題

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

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

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

處理驗證要求

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

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

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

每當您的端點收到驗證要求時，都必須執行以下作業：

• 驗證 hub.verify_token 值是否與設定 Webhook 時在「驗證權杖」欄位中所設定的字串相符。
• 以 hub.challenge 值回覆。

Webhook 安全性

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

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

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

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

使用 API 呼叫訂閱 Webhooks

讀取或修改 Webhook 訂閱的 API 呼叫需要使用應用程式權杖（不是一般自訂整合權杖）進行。您可以透過結合應用程式編號、「|」符號和應用程式密鑰來產生應用程式權杖。

例如：

取得目前的 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 文件。