登入開始免費試用
easyCoexistence 官方 API

Facebook Webhook 驗證:hub.challenge 與 X-Hub-Signature-256

Facebook 以 GET 請求驗證 webhook 端點,請求帶有 hub.mode 設為 subscribe、hub.verify_token 與 hub.challenge;端點核對權杖與應用程式控制台中的設定相符後,以 hub.challenge 作為主體回傳。之後每個事件都以 POST 傳送,其 X-Hub-Signature-256 標頭為 sha256= 加上以應用程式密鑰為金鑰、對負載計算的 HMAC-SHA256。

easyCoexistence 為您連接的每個專頁處理 Meta 的部分:其應用程式回應 hub.challenge、核對 X-Hub-Signature-256,並將專頁訂閱至動態消息、訊息與提及,然後以該專頁專屬的密鑰簽名 X-EC-Signature,將事件轉發至您的 HTTPS 端點。

subscribe

hub.mode 是 Meta 驗證請求中固定帶有的值;hub.challenge 是需要回傳的整數。

sha256=

X-Hub-Signature-256 的前綴,其後接 Meta 以負載與 App Secret 生成的 SHA256 簽名。

5 seconds

Messenger webhook 端點回應每則通知並傳回 200 OK 的時限。

1 hour

失敗傳送次數達到多少次前,會發出 Webhooks Disabled 警報,並取消應用程式對專頁的訂閱。

36 hours

Meta 以遞減頻率重試失敗專頁通知的時長,之後即捨棄。

Meta 的驗證請求包含什麼?

一個 GET 請求會傳送到回調 URL,只要在應用程式控制台設定 Webhooks 產品,或透過 /{app-id}/subscriptions 建立訂閱,就會發出。請求附帶三個查詢參數:

  • hub.mode:固定為 subscribe。
  • hub.challenge:端點必須回傳的整數。
  • hub.verify_token:在控制台的驗證權杖欄位輸入的字串。
  • PHP 會把點號換成底線,因此讀取時變為 hub_mode、hub_challenge 與 hub_verify_token。

端點應如何回應?

回傳 200,主體僅為 hub.challenge 的值,但只有在 hub.mode 為 subscribe 且 hub.verify_token 相符時才這樣做;其他情況回傳 403,與 Meta 的範例應用程式一致。控制台會顯示端點是否通過,/{app-id}/subscriptions 則回傳成功或錯誤。端點必須使用 HTTPS 並具有有效的 TLS 或 SSL 憑證,因為不支援自簽憑證。

X-Hub-Signature-256 如何計算?

以應用程式密鑰為金鑰,對請求負載計算 HMAC-SHA256,結果以小寫十六進位表示,並加上 sha256= 前綴。Meta 的 Messenger 指南補充,簽名計算的負載會先將 Unicode 轉義,因此 äöå 這類字串會以 \u00e4\u00f6\u00e5 計算:應對收到的原始主體直接計算雜湊,不可使用解碼或重新序列化的副本。Meta 表示驗證為可選項,但強烈建議進行驗證。

如何在程式碼中核對?

保留原始位元組,計算 HMAC,以恆定時間比較,然後才解析。Flask 的 get_data 會原樣回傳主體,正是簽名計算所依據的內容;若先解析再序列化,位元組就會改變。以下是一個小型端點,同時處理驗證與每個 POST 的核對:

Python: hub.challenge and X-Hub-Signature-256
import hashlib, hmac, os
from flask import Flask, abort, request

app = Flask(__name__)
VERIFY_TOKEN = os.environ["VERIFY_TOKEN"]
APP_SECRET = os.environ["APP_SECRET"].encode()

@app.get("/webhooks/facebook")
def verify():
    token = request.args.get("hub.verify_token", "")
    if request.args.get("hub.mode") == "subscribe" and hmac.compare_digest(token.encode(), VERIFY_TOKEN.encode()):
        return request.args.get("hub.challenge", ""), 200
    abort(403)

@app.post("/webhooks/facebook")
def receive():
    raw = request.get_data()  # the bytes Meta signed
    expected = "sha256=" + hmac.new(APP_SECRET, raw, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected.encode(), request.headers.get("X-Hub-Signature-256", "").encode()):
        abort(401)
    # answer at once; hand request.get_json() to a queue for the work
    return "EVENT_RECEIVED", 200

驗證之後 Meta 期望什麼?

每則通知都要以 200 OK 回應;Messenger 事件須在 5 秒內回應。Meta 每次傳送最多批次 1,000 筆更新,但不保證如此,並以下列方式處理失敗:

  • 專頁通知:立即重試,之後以遞減頻率再重試數次,持續 36 小時,然後捨棄。
  • Messenger 通知:立即重試數次;失敗持續 15 分鐘後,會向開發者帳戶發出警報。
  • 失敗持續一小時後,會發出 Webhooks Disabled 警報,應用程式會被取消對專頁的訂閱,直至重新訂閱為止。
  • 重試可能導致事件重複傳送且順序錯亂,因此需要去重,並依訊息的時間戳記排序。
  • 之前的通知之後無法查詢,因此須在收到時儲存所需內容。

easyCoexistence 如何通過 Meta 的檢查?

其 Meta 應用程式對所連接的專頁只有一個回調 URL,該端點自行執行兩項檢查。只有在 hub.mode 為 subscribe 且驗證權杖相符時才回應 GET,比對以恆定時間進行,否則回傳 403;它以原始文字讀取每個 POST,使用應用程式密鑰重新計算 X-Hub-Signature-256,簽名不符則以 401 拒絕,並立即回應 Meta,事件在回應之後才處理。

easyCoexistence 如何為轉發內容簽名?

使用它自己的簽名,因為 Meta 的標頭只能以 easyCoexistence 的應用程式密鑰核對,且不會被傳遞。每個已連接且已設定端點的專頁項目,都會以 JSON 形式 POST 到該端點,內容為 {platform, account_id, external_id, entry},並附帶格式為 t=<unix>,v1=<hex> 的 X-EC-Signature 標頭;其中 v1 是以該專頁的簽署密鑰為金鑰,對時間戳記、一個點號與原始主體計算的 HMAC-SHA256:

  • 密鑰以 whsec_ 開頭,只顯示一次,可透過 Partner API 的 set_social_webhook_destination 或 PUT /channels/:id/webhook 取得。
  • 重新設定 URL 會發出新密鑰;將 URL 設為 null 則關閉轉發。
  • 每次轉發只傳送一次,最多等待 8 秒,不跟隨重新導向,且只傳送至解析為公共 IP 的 HTTPS 位址。
  • 事件不會保存副本,因此無法從中重試。

如何驗證 X-EC-Signature?

將標頭拆分為 t 與 v1,拒絕超過 5 分鐘的時間戳記,以該專頁的簽署密鑰對 t、一個點號與原始主體重新計算 HMAC,並以恆定時間比較。以下是 Node.js 的寫法,主體以原始位元組保存:

Node.js: checking X-EC-Signature on a forwarded event
import crypto from "node:crypto";
import express from "express";

const app = express();
const SECRET = process.env.EC_SIGNING_SECRET; // whsec_..., shown once

app.post("/events/facebook", express.raw({ type: "application/json" }), (req, res) => {
  const sig = Object.fromEntries(
    String(req.get("X-EC-Signature") ?? "").split(",").map((part) => part.split("="))
  );
  const fresh = Math.abs(Date.now() / 1000 - Number(sig.t)) <= 300;
  const expected = crypto
    .createHmac("sha256", SECRET)
    .update(Buffer.concat([Buffer.from(`${sig.t}.`), req.body]))
    .digest("hex");
  const ok = fresh && typeof sig.v1 === "string" && sig.v1.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig.v1));
  if (!ok) return res.sendStatus(401);
  res.sendStatus(200); // answer first: forwards are not retried
  const { platform, account_id, external_id, entry } = JSON.parse(req.body.toString("utf8"));
  // queue entry for the work
});

常見錯誤

  • 把 hub.challenge 包裝在 JSON 或引號中。200 的主體必須是 challenge 值本身。
  • 在 JSON 解析器之後計算 HMAC。解析再序列化會改變位元組,而 Meta 簽名的負載是經過 Unicode 轉義的,因此應對原始主體計算雜湊。
  • 先做工作再回應。Messenger 要求 5 秒內回應 200,連續一小時失敗會讓應用程式取消對專頁的訂閱。
  • 核對 Meta 對轉發事件的簽名。Meta 以 easyCoexistence 的應用程式密鑰簽名;轉發事件附帶的 X-EC-Signature 須以該專頁的簽署密鑰核對。
使用 EasyCoexistence 完成這項設定

每個連接每月 US$ 9 至 US$ 0.75,連接越多越便宜,前 3 天免費。

常見問題

驗證權杖從哪裡來?

由您自行選擇。它是在應用程式控制台設定 Webhook 時,於驗證權杖欄位輸入的字串,或是傳送至 /{app-id}/subscriptions 的 verify_token。

可以用 curl 測試驗證嗎?

可以。Meta 的 Messenger 指南會傳送帶有 hub.verify_token、hub.challenge=CHALLENGE_ACCEPTED 與 hub.mode=subscribe 的 GET,正常運作的端點會回傳 CHALLENGE_ACCEPTED。

如果端點失敗一小時會怎樣?

Meta 會發出 Webhooks Disabled 警報,並取消應用程式對專頁的訂閱。修復端點後,請透過 subscribed_apps 重新訂閱專頁。

接收專頁的 webhook 是否需要自己的 Meta 應用程式?

不需要。使用 easyCoexistence 時,Meta 會將事件傳送至其應用程式,再由其將每個專頁的事件轉發至您設定的端點,並以 X-EC-Signature 簽名。

繼續閱讀

兩分鐘內連接您的第一個頻道。

無需等待平台審核。連接 WhatsApp、Instagram、TikTok 或其他頻道,然後請您的 AI 發佈貼文、回覆訊息或匯報數據,並看着它運作。

  • 免費試用 3 天
  • 隨時取消
  • 只用官方 API
  • 24/7 監察

驗證日期