Webhooks

概覽

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

這樣能讓應用程式確切知道變更何時發生，不需依賴連續或定期發出 Graph API 要求來取得最新內容，因此可讓應用程式更有效率。

Workplace 專用 Webhook 支援由支援 Graph 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 值回應。

Webhooks 安全

所有向開發人員定義的回呼網址所發出的 Webhook 呼叫均透過 HTTPS 完成，可在傳輸層級確保 Webhook 裝載的安全。

為進一步保障安全，每個 POST 裝載中還加入了 HTTP 頁首 X-Hub-Signature-256。您應以此驗證裝載是否來自 Meta 伺服器。

如要了解此行為的完整詳情，請參閱 Webhooks 框架文件。

所有向開發人員定義的回呼網址所發出的 Webhook 呼叫均透過 HTTPS 完成，可在傳輸層級確保 Webhook 裝載的安全。

使用 API 呼叫訂閱 Webhooks

如要發出 API 呼叫來讀取或修改 Webhook 訂閱，需要使用憑證，而不是平時用的自訂整合工具憑證。將應用程式編號、「|」符號和應用程式密鑰串連在一起，即為應用程式憑證。

例如：

取得目前 Webhooks 訂閱（使用應用程式憑證）

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

新增新的 Webhooks 訂閱（使用應用程式憑證）

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

與轉銷商相關的事件。

連結

如需更多資訊，請參閱連結主題參考文件。

知識資料庫

如需更多資訊，請參閱知識資料庫類別 Graph API 文件。