Instagram Webhook 驗證:hub.challenge 與 X-Hub-Signature-256
設定 Instagram Webhook 需要一個 HTTPS 端點,用以回應 Meta 的驗證 GET 請求。該請求載有值為 subscribe 的 hub.mode、hub.verify_token 與 hub.challenge。端點核對驗證權杖後,須回傳 hub.challenge 值。應用程式訂閱欄位後,Meta 會以 POST 傳送 JSON 事件,並以應用程式密鑰簽署,簽章載於 X-Hub-Signature-256。每個帳戶亦須透過其 subscribed_apps 邊緣完成訂閱。
easyCoexistence 負責 Meta 的一端:其應用程式通過驗證、核對 X-Hub-Signature-256、為每個已連接的 Instagram 帳戶訂閱留言、訊息與提及,並以各帳戶獨立的密鑰簽署 X-EC-Signature,將事件轉發至您的 HTTPS 端點,同時全天候監察每條連接。
hub.mode 的值在 Meta 的驗證請求中必定附帶。
Meta 以遞減頻率重試失敗通知的時段,之後便會捨棄。
向開發者帳戶發出警示前,訊息傳遞失敗的持續時間。
訊息傳遞持續失敗達到一定時長後,系統會發出 Webhooks Disabled 警示,並取消應用程式對該帳戶的訂閱。
Meta 規定應用程式須為 Live 模式,才會接收用戶帳戶的通知。
Instagram Webhook 設定的運作方式是怎樣的?
按 Meta 指南的次序,分四個步驟進行。端點須先通過驗證,才能選擇任何欄位;應用程式須為 Live 模式,才能接收用戶帳戶的通知;正式環境亦須完成商業驗證。
驗證請求包含什麼?
在應用程式控制台設定 Webhooks 產品後,系統會向回呼 URL 發出 GET 請求。若 hub.verify_token 與端點自身的權杖相符,端點須回傳 200,並以 hub.challenge 值作為整個回應內容;否則回傳 403。控制台會顯示端點是否通過驗證。
- hub.mode:固定為 subscribe。
- hub.challenge:Meta 生成的整數,端點須回傳此值。
- hub.
verify_token:在控制台「Verify Token」欄位輸入的字串,只有 Meta 與端點應知道。 - PHP 中,名稱內的點會轉為底線,因此這些值會以
hub_mode、hub_challenge與hub_verify_token接收。
GET https://<YOUR_HOST>/webhooks/instagram
?hub.mode=subscribe
&hub.challenge=1158201444
&hub.verify_token=<YOUR_VERIFY_TOKEN>
HTTP/1.1 200 OK
Content-Type: text/plain
1158201444回呼 URL 與欄位在哪裡設定?
在應用程式控制台的「Instagram」下,「API setup with Instagram login」之「Configure webhooks」中設定:回呼 URL 與驗證權杖都填在這裡,儲存後即觸發驗證請求。Instagram 產品預設已訂閱 comments、live_comments、message_reactions、messages、messaging_optins、messaging_postbacks、messaging_referral 與 messaging_seen,「Manage」可取消其中任何一項的訂閱。「Test」按鈕會為所選欄位發送一則示範通知。
X-Hub-Signature-256 如何核對?
Meta 會以應用程式密鑰為金鑰,對負載計算 HMAC-SHA256,並以 sha256= 加上十六進位摘要的格式,放入 X-Hub-Signature-256。接收端須對原始請求內容計算相同的 HMAC,再以恆定時間與標頭比對。Meta 的訊息指南指出,簽章涵蓋的是已將 Unicode 轉義的負載,因此對解碼或重新序列化後的 JSON 進行雜湊,結果會不同。
import crypto from "node:crypto";
import express from "express";
const app = express();
const { VERIFY_TOKEN, APP_SECRET } = process.env;
// Verification request: send hub.challenge back when the token matches
app.get("/webhooks/instagram", (req, res) => {
const ok = req.query["hub.mode"] === "subscribe" &&
req.query["hub.verify_token"] === VERIFY_TOKEN;
if (!ok) return res.sendStatus(403);
res.status(200).type("text/plain").send(req.query["hub.challenge"]);
});
// Event notification: check the signature over the raw bytes
app.post("/webhooks/instagram", express.raw({ type: "application/json" }), (req, res) => {
const expected = Buffer.from(
"sha256=" + crypto.createHmac("sha256", APP_SECRET).update(req.body).digest("hex")
);
const given = Buffer.from(req.get("X-Hub-Signature-256") ?? "");
if (given.length !== expected.length || !crypto.timingSafeEqual(given, expected)) {
return res.sendStatus(401);
}
res.sendStatus(200); // answer first, work after
const body = JSON.parse(req.body.toString("utf8"));
// hand body.entry to a queue or background job
});
app.listen(3000);為何只有應用程式密鑰能核對?
因為簽章是以該密鑰為金鑰的 HMAC。沒有密鑰,無人能算出預期值;持有負載副本的人也無法偽造,因此核對工作必須在為該應用程式接收 Meta 請求的伺服器上進行。Meta 要求應用程式密鑰、存取權杖與用戶端憑證不得出現在日誌或支援請求中。若事件由另一應用程式轉發,則無法核對 Meta 的簽章,只能依賴該應用程式自身的簽章。
為何每個帳戶都需要各自訂閱?
因為應用程式控制台決定應用程式可接收的內容,而帳戶的通知只會在該帳戶也完成訂閱後才開始。使用 Instagram Login 時,以帳戶的 Instagram 用戶存取權杖,向 graph.instagram.com 發送 POST /<IG_ID>/subscribed_apps,並以逗號分隔列出應用程式所選的 subscribed_fields 欄位。成功的呼叫會回傳 success 為 true。
POST https://graph.instagram.com/<IG_ID>/subscribed_apps
?subscribed_fields=comments,messages
&access_token=<INSTAGRAM_USER_ACCESS_TOKEN>
{ "success": true }Meta 在傳送失敗時會怎樣處理?
Meta 會重試,之後放棄。Meta 指南要求每則通知都回傳 200 OK,並提醒批次傳送(最多 1,000 項更新)不獲保證。失敗的更新會立即重試,之後以遞減頻率再重試數次,為期 36 小時,之後便會捨棄,因此同一事件可能重複抵達。訊息事件遵循 Meta 的訊息傳遞規則,處理更快:
- 預期在 5 秒內回傳 200 OK;傳送失敗會獲得數次即時重試,因此須以訊息 mid 去除重複。
- 持續失敗 15 分鐘後,系統會向開發者帳戶發出警示。
- 持續失敗一小時後,會發出 Webhooks Disabled 警示,應用程式亦會取消該帳戶的 Webhook 訂閱,直至重新訂閱為止。
- 中斷期間發出的訊息可能亂序抵達,因此須按時間戳記排序。
沒有收到任何事件時,應檢查什麼?
請依以下次序,核對 Meta 的疑難排解清單。此清單涵蓋大部分沒有回應的端點:
- 回呼 URL 已通過驗證,可透過 HTTPS 連接,並具有有效憑證;不支援自簽憑證。
- 應用程式已選取該欄位,並具備所需的存取級別,comments 與
live_comments須具備 Advanced Access。 - 已透過
subscribed_apps為該帳戶開啟通知,且權杖來自同一登入設定。 - 帳戶符合該欄位的規則:留言通知需要由公開帳戶擁有的媒體。
- 伺服器在開始耗時工作前,即先回傳成功。
為何 easyCoexistence 要重新簽署轉發的事件?
因為 Meta 的簽章無法隨事件轉送。easyCoexistence 的應用程式接收 Meta 的傳送,以自身的應用程式密鑰核對 X-Hub-Signature-256,隨即回應 Meta,並將每個已連接帳戶的條目,以 platform、account_id、external_id 與 entry 組成的新內容,發送至該帳戶所設定的端點。Meta 的標頭不會轉送,若無該密鑰亦無法核對,因此每次轉發都會附上 Content-Type: application/json 與 X-EC-Signature,並以只屬於該帳戶的密鑰簽署。
如何核對 X-EC-Signature?
標頭格式為 t=<unix>,v1=<hex>,其中 v1 是以帳戶簽署密鑰為金鑰、對時間戳記、句點與原始內容計算的十六進位 HMAC-SHA256。請依接收的原始位元組重新計算,以恆定時間比對,並拒絕超過 5 分鐘的時間戳記。
- 密鑰以 whsec_ 開頭,設定 URL 時由
set_social_webhook_destination或 PUT /channels/:id/webhook 顯示一次。 - 重新設定 URL 會發出新密鑰;URL 設為 null 則停止轉發。
- 每個事件只傳送一次,最多等候 8 秒,不跟隨重新導向,目標須為 HTTPS 地址,且解析至公開 IP。
- 移除連接時,會取消該帳戶在 Meta 的 Webhook 訂閱,並清除其端點與密鑰。
import hashlib, hmac, time
def verify_ec_signature(raw_body: bytes, header: str, secret: str) -> bool:
"""Check X-EC-Signature on an event forwarded by easyCoexistence."""
parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
t, v1 = parts.get("t", ""), parts.get("v1", "")
if not t.isdigit() or abs(time.time() - int(t)) > 300:
return False # missing, malformed or older than 5 minutes
expected = hmac.new(secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected.encode(), v1.encode())常見錯誤
- 以 JSON 或引號包裹 hub.challenge 回傳。Meta 要求以 200 狀態碼回傳 hub.challenge 值本身作為內容。
- 對已解析的內容進行雜湊。JSON 內容解析器會捨棄 Meta 所簽署的確切位元組,因此須保留原始內容計算 HMAC,之後才解析。
- 只訂閱應用程式,卻忘記帳戶。在 POST /<IG_ID>/subscribed_apps 對某帳戶成功之前,該帳戶不會收到任何通知。
- 讓端點故障長達一小時。Meta 會停用訊息 Webhook,並取消應用程式對該帳戶的訂閱,之後須重新訂閱。
使用 set_social_webhook_destination 或 Partner API 即可啟用。每條連接每月 US$ 9 起,連接越多越便宜,最低降至 US$ 0.75,首 3 天免費。
常見問題
Instagram Webhook 中的 hub.challenge 是什麼?
Meta 在驗證 GET 中發送的整數。端點核對 hub.verify_token 後,會將它以回應內容回傳,藉此證明其掌控該 URL。
為何 PHP 中缺少 hub.mode 與 hub.challenge?
PHP 會把參數名稱中的點轉為底線,因此 Meta 的驗證值會以 hub_mode、hub_challenge 與 hub_verify_token 接收。
Meta 停用 Instagram Webhook 後,如何重新啟用?
修正端點,然後以相同欄位再次呼叫 POST /<IG_ID>/subscribed_apps 為該帳戶重新訂閱。
自簽憑證能用於 Instagram Webhook 端點嗎?
不能。Meta 不支援自簽憑證:回呼 URL 須可透過 HTTPS 連接,並具有有效憑證,這是 Meta 疑難排解清單的第一項。
繼續閱讀
兩分鐘內連接您的第一個頻道。
無需等待平台審核。連接 WhatsApp、Instagram、TikTok 或其他頻道,然後請您的 AI 發佈貼文、回覆訊息或匯報數據,並看着它運作。
- 免費試用 3 天
- 隨時取消
- 只用官方 API
- 24/7 監察
驗證日期