新手指南

本文件會說明如何設定 Webhooks，以便在您的應用程式用戶為其用戶相片發佈任何變更時通知您。當您明白如何設定此 Webhooks 後，便知道如何設定所有 Webhooks。

設定任何 Webhooks 時，您都需要執行以下操作：

在安全的伺服器上建立可處理 HTTPS 要求的端點。
在您應用程式的應用程式管理中心中配置 Webhooks 產品。

下文將詳細說明這些步驟。

建立端點

您的端點必須能夠處理兩類 HTTPS 要求：驗證要求和事件通知。這兩類要求都使用 HTTPs，因此您的伺服器必須已正確配置並安裝有效的 TLS 或 SSL 憑證。系統不支援自行簽署憑證。

以下各部分將說明每類要求中的內容，以及回應這些要求的方式。或者，您可以使用我們的範例應用程式；此應用程式已配置好，可以處理這些要求。

驗證要求

每當您在應用程式管理中心配置 Webhooks 產品時，我們都會將一項 GET 要求傳送至您的端點網址。驗證要求包含下列查詢字串參數，這些參數會附加至端點網址的尾段，類似下方所示：

驗證要求範例

GET https://www.your-clever-domain-name.com/webhooks? hub.mode=subscribe& hub.challenge=1158201444& hub.verify_token=meatyhamhock

參數	值範例	說明
`hub.mode`	`subscribe`	此值一律設為 `subscribe`。
`hub.challenge`	`1158201444`	您必須傳回給我們的 `int`。
`hub.verify_token`	`meatyhamhock`	我們從您應用程式的應用程式管理中心「驗證憑證」欄位所獲取的字串。當您完成 Webhooks 配置設定步驟時，便會設定此字串。

備註：PHP 會將參數名稱中的英文句號（.）改為底線（_）。

確認驗證要求

每當您的端點收到驗證要求時，其都必須如下操作：

確認 hub.verify_token 值與您在應用程式管理中心配置 Webhooks 產品時，在驗證憑證欄位所設定的字串相符（您尚未設定此憑證）。
以 hub.challenge 值回應。

如果您正在應用程式管理中心配置 Webhooks 產品並因此觸發驗證要求，管理中心會表明您的端點是否已正確地驗證要求。如果您使用 Graph API 的 /app/subscriptions 端點來配置 Webhooks 產品，此 API 會透過回應表明設定成功還是失敗。

事件通知

當您配置 Webhooks 產品時，您將會訂閱某個 object 類型的特定 fields（例如 user 物件的 photos 欄位）。每當其中某個欄位出現變更時，我們都會向您的端點傳送 POST 要求，其中包含描述相關變更的 JSON 裝載。

舉例來說，如果您已訂閱 user 物件的 photos 欄位，而且您應用程式的其中一位用戶發佈了一張相片，我們會向您傳送如下所示的 POST 要求：

POST / HTTPS/1.1 Host: your-clever-domain-name.com/webhooks Content-Type: application/json X-Hub-Signature-256: sha256={super-long-SHA256-signature} Content-Length: 311 { "entry": [ { "time": 1520383571, "changes": [ { "field": "photos", "value": { "verb": "update", "object_id": "10211885744794461" } } ], "id": "10210299214172187", "uid": "10210299214172187" } ], "object": "user" }

裝載內容

裝載會包含描述相關變更的物件。配置 Webhooks 產品時，您可以指明裝載應該只包含已更改欄位的名稱，還是亦應包含新值。

我們會將所有裝載的格式設定為 JSON，這樣您便可以使用常見的 JSON 剖析方法或套件來剖析裝載。

我們不會儲存傳送給您的任何 Webhooks 事件通知數據，因此請務必擷取並儲存您想保留的任何裝載內容。

大部分裝載都包含以下常見屬性，但每個裝載的內容和結構都各有不同，具體視乎您訂閱的物件欄位而定。請參閱每個物件的參考文件，以了解哪些欄位會包含在內。

屬性	說明	類型
`object`	物件類型（如 `user`、`page` 等）	`string`
`entry`	包含描述變更的物件之陣列。來自不同物件但屬於相同類型的多項變更可能會合併起來以作批次處理。	`array`
`id`	物件編號	`string`
`changed_fields`	表示已更改欄位的名稱之字串陣列。僅在以下情況下包含在內：當您在自家應用程式的應用程式管理中心中配置 Webhooks 產品時停用了「包含數值」設定。	`array`
`changes`	包含描述已更改欄位的物件及其新值之陣列。僅在以下情況下包含在內：當您在自家應用程式的應用程式管理中心配置 Webhooks 產品時啟用了「包含數值」設定。	`array`
`time`	表明傳送事件通知的時間（而非觸發該通知的變更發生時間）之 UNIX 時戳。	`int`

驗證裝載

我們會使用 SHA256 簽章簽署所有事件通知裝載，而且在相關要求的 X-Hub-Signature-256 標題中包含簽章並在前面加上 sha256=。您不一定要驗證裝載，但我們建議您這樣做。

如要驗證裝載，請按照下列步驟操作：

使用裝載和您應用程式的應用程式密鑰來產生 SHA256 簽章。
比較您的簽章與 X-Hub-Signature-256 標題中的簽章（sha256= 之後的所有內容）。如果簽章一致，則表示裝載真實有效。

回應事件通知

您的端點應該以 200 OK HTTPS 回應所有事件通知。

頻率

系統會彙整事件通知，並以一個批次的形式傳送最多 1,000 項更新。不過，批量處理不保證一定可行，因此請務必將您的伺服器調整為可個別處理每個 Webhooks。

如果無法將任何更新傳送至您的伺服器，我們將立即重試，然後在接下來的 36 小時內再重試幾次，但重試頻率會下降。您的伺服器應在這些情況下處理重複數據。系統會在 36 小時後捨棄未確認的回應。

備註：傳送 Messenger 事件通知的頻率並不相同。請參閱 Messenger 平台 Webhooks 文件以了解更多資訊。

配置 Webhooks 產品

在您的端點或範例應用程式準備就緒後，請使用您應用程式的應用程式管理中心來新增及配置 Webhooks 產品。您亦可透過適用於所有 Webhooks（Instagram 除外）的 /{app-id}/subscriptions 端點，透過程式輔助的方式完成操作。

在本例子中，我們將使用管理中心來配置 Webhooks，且此 Webhooks 會訂閱您應用程式任何用戶之相片的任何變更。

在應用程式管理中心，前往「產品」>「Webhooks」，然後從下拉式選單中選擇「用戶」，再點擊「訂閱此物件」。
選擇相關用戶物件。
在「回呼網址」欄位中輸入端點網址，並在「驗證憑證」欄位中輸入字串。我們會在所有驗證要求中加入此字串。如果您正在使用我們其中一個範例應用程式，則此字串應該就是您用於自家應用程式 TOKEN 配置變數的同一組字串。
如果您希望事件通知裝載包含已更改欄位的名稱及其新值，請將包含數值切換為是。
輸入端點網址和驗證憑證字串。
點擊驗證並儲存後，我們便會傳送驗證要求給您的端點，而您必須驗證此要求。如果您的端點成功驗證了要求，您應該會看到以下畫面：
驗證成功。
最後一個步驟是訂閱個別欄位。訂閱 photos 欄位，並傳送測試事件通知。
訂閱用戶物件的相片欄位。
如果您的端點設定正確，它應該會驗證裝載，並會在驗證成功後，執行您為其設定的任何程式碼。如果您正在使用我們的範例應用程式，請在網頁瀏覽器中載入應用程式網址。畫面應該會顯示裝載內容：
顯示測試通知裝載的範例應用程式。

後續步驟

既然您已知道如何設定 Webhooks，不妨參閱其他文件，了解為特定產品設定 Webhooks 時所涉及的額外步驟：