Meta Webhooks

開始使用

這份文件說明 Webhook 的設定方式，以在每次應用程式用戶對其用戶相片發佈任何變更時通知您。一旦瞭解此 Webhook 的設定方式後，您就能知道如何設定所有 Webhook。

設定任何 Webhook 時，您都必須進行下列動作：

  1. 在可處理 HTTPS 要求的安全伺服器上建立端點。
  2. 在應用程式的應用程式主控板中設定 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 產品（並因此觸發驗證要求），主控板會指出您的端點是否正確驗證要求。如果您正使用圖形 API 的 /app/subscriptions 端點設定 Webhooks 產品，API 將透過回應表示成功或失敗。

事件通知

當您設定 Webhooks 產品時，您將訂閱 object 類型上的特定 fields（例如，user 物件上的 photos 欄位）。每次其中一個欄位發生變更時，我們會傳送包含描述變更之 JSON 承載的 POST 要求至您的端點。

例如，如果您訂閱了 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 剖析方法或套件來剖析承載。

我們不會儲存任何傳送給您的 Webhook 事件通知資料，因此請務必擷取或儲存您想保留的任何承載內容。

多數承載將包含下列一般屬性，但每個承載的內容和結構仍會視您所訂閱的物件欄位而有所不同。如需瞭解將包含的欄位，請參閱各物件的參考文件。

屬性 說明 類型

object

物件的類型（例如，user、page 等）

string

entry

包含描述變更之物件的陣列。來自不同物件但相同類型的多項變更可能會批次一起處理。

array

id

物件的編號

string

changed_fields

表示已變更欄位名稱的字串陣列。只有當您在應用程式的應用程式主控板中設定 Webhooks 產品時停用包含值的設定，才會包含此項目。

array

changes

包含描述已變更欄位及其新值之物件的陣列。只有當您在應用程式的應用程式主控板中設定 Webhooks 產品時啟用包含值的設定，才會包含此項目。

array

time

表示傳送事件通知時間的 UNIX 時間戳記（不是觸發通知的變更所發生的時間）。

int

驗證承載

我們會在所有事件通知承載上簽署 SHA256 簽章，並將簽章包含在要求的 X-Hub-Signature-256 標頭中，在開頭加上 sha256=。您不一定要驗證承載，但建議最好這樣做。

驗證承載：

  1. 使用承載和應用程式的應用程式密鑰產生 SHA256 簽章。
  2. 比較您的簽章與 X-Hub-Signature-256 標頭中的簽章（sha256= 之後的內容）。如果簽章相符，表示承載是真的。

回覆事件通知

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

頻率

事件通知會持續彙總，並以最多 1,000 個更新進行批次傳送。但無法保證能使用批次功能，因此請務必調整伺服器以個別處理各 Webhook。

如果傳送至您伺服器的任何更新失敗，我們將立即重試，然後在接下來的 36 小時內，以遞減的頻率再重試幾次。您的伺服器應該要能夠處理這些情況下的重複資料刪除。未確認的回應會在 36 小時後遭到捨棄。

注意：系統傳送 Messenger 事件通知的頻率不同。如需詳細資訊，請參閱 Messenger 平台 Webhooks 文件。

配置 Webhooks 產品

您的端點或應用程式範例就緒後，請使用應用程式的應用程式主控板新增並配置 Webhooks 產品。除了 Instagram 外，您還可以使用所有 Webhooks 的 /{app-id}/subscriptions 端點，以程式設計的方式執行此操作。

在這個範例中，我們將使用主控板設定 Webhook，以訂閱任何應用程式用戶的任何相片變更。

  1. 在應用程式主控板中，前往產品 > Webhooks，並從下拉式功能表選擇用戶，然後點擊「訂閱此物件」。
    選擇用戶物件。

  2. 在回呼網址欄位輸入端點網址，並在驗證權杖欄位輸入字串。我們會在所有驗證要求中包含此字串。如果您使用我們其中一個應用程式範例，這個字串應該與應用程式 TOKEN 設定變數所使用的字串相同。

    如果您希望事件通知承載包含已變更的欄位名稱及其新值，請將包含值切換為是。
    輸入端點網址和驗證權杖字串。

  3. 點擊「驗證並儲存」後，我們會向您的端點傳送驗證要求，您必須驗證才能繼續進行。如果端點成功驗證要求，您應該會看見：

    成功驗證。

  4. 最後一步是訂閱個別欄位。訂閱 photos 欄位，並傳送測試事件通知。

    訂閱用戶物件上的相片欄位。

    如果端點設定正確，端點應該會驗證承載，並執行您設定其應在成功驗證後執行的任何程式碼。如果您使用我們的應用程式範例，請在網頁瀏覽器中載入應用程式網址。瀏覽器應該會顯示承載的內容：

    顯示測試通知承載的應用程式範例。

後續步驟

現在您已知道如何設定 Webhooks，接下來您可能會想參閱其他文件，以瞭解其他為特定產品設定 Webhooks 的步驟：