אימות וובהוק (Webhook) של Facebook: hub.challenge ו-X-Hub-Signature-256
Facebook מאמת נקודת קצה של וובהוק (Webhook) באמצעות בקשת GET שנושאת את hub.mode בערך subscribe, את hub.verify_token ואת hub.challenge. נקודת הקצה בודקת את האסימון מול זה שב-App Dashboard ומחזירה את ערך האתגר כגוף התגובה. לאחר מכן כל אירוע מגיע כ-POST החתום ב-X-Hub-Signature-256: sha256= ואחריו ה-HMAC-SHA256 של ה-payload, במפתח סוד האפליקציה.
easyCoexistence מטפלת בצד של Meta עבור כל עמוד שאתם מחברים: האפליקציה שלה עונה ל-hub.challenge, בודקת את X-Hub-Signature-256 ורושמת את העמוד ל-feed, messages ו-mention, ואז מעבירה את האירועים לנקודת הקצה ה-HTTPS שלכם, חתומים ב-X-EC-Signature ובסוד ייעודי לאותו עמוד.
הערך שהשדה hub.mode נושא תמיד בבקשת האימות של Meta; hub.challenge הוא מספר שלם שיש להחזיר.
הקידומת של X-Hub-Signature-256, ואחריה חתימת SHA256 שנוצרת על ידי Meta מה-payload ומסוד האפליקציה (App Secret).
תוך כמה זמן נקודת הקצה של וובהוק של Messenger צריכה לענות לכל עדכון ב-200 OK.
מספר המשלוחים הכושלים שמותרים לפני התראת Webhooks Disabled, ואחריה מבוטל המינוי של האפליקציה לעמוד.
כמה זמן Meta מנסה שוב עדכון עמוד שנכשל, בתדירות יורדת, לפני שהוא נזרק.
מה כוללת בקשת האימות של Meta?
בקשת GET אל כתובת ה-callback, שנשלחת בכל פעם שמוצר ה-Webhooks מוגדר ב-App Dashboard או שנוצר מינוי דרך /{app-id}/subscriptions. יחד איתה מגיעים שלושה פרמטרי שאילתה:
- hub.mode: תמיד subscribe.
- hub.challenge: מספר שלם שנקודת הקצה חייבת להחזיר.
- hub.
verify_token: המחרוזת שהוזנה בשדה 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 של גוף הבקשה, עם המפתח App Secret של האפליקציה, בהצגה הקסדצימלית באותיות קטנות אחרי sha256=. מדריך Messenger של Meta מוסיף שהחתימה מכסה את ה-payload כשתווי Unicode מקודדים בצורת escape, כך שמחרוזת כמו äöå נחשבת כ-\u00e4\u00f6\u00e5: יש לחשב את ה-hash על הגוף הגולמי כפי שהתקבל, ולא על עותק מפוענח או מסודר מחדש. Meta אומר שהאימות אופציונלי, אך ממליץ עליו בחום.
איך בודקים את זה בקוד?
שומרים את הבייטים הגולמיים, מחשבים את ה-HMAC, משווים בזמן קבוע, ורק אז מפרסרים. get_data של Flask מחזיר את הגוף ללא שינוי, וזה בדיוק מה שהחתימה חושבה עליו; פרסור תחילה ואחריו סידור מחדש היה משנה את הבייטים. להלן נקודת קצה קטנה שעונה לאימות ובודקת כל POST:
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 לכל עדכון, תוך 5 שניות באירועי Messenger. Meta מאגד עד 1,000 עדכונים בכל משלוח בלי להבטיח זאת, ומטפל בכשלונות כך:
- עדכוני עמוד: נשלחים שוב מיד, ואחר כך כמה פעמים נוספות בתדירות יורדת לאורך 36 שעות, ואז נזרקים.
- עדכוני Messenger: נשלחים שוב כמה פעמים מיד; אחרי 15 דקות של כשלונות מגיעה התראה לחשבון המפתח.
- אחרי שעה של כשלונות מגיעה התראת Webhooks Disabled, והאפליקציה מבוטלת מהמינוי לעמוד עד שתירשם שוב.
- ניסיונות חוזרים עלולים למסור אירוע פעמיים ובסדר שגוי, ולכן יש להסיר כפילויות ולמיין את ההודעות לפי חותמת הזמן שלהן.
- אירועים קודמים אינם ניתנים לשאילתה מאוחר יותר, ולכן יש לשמור את מה שצריך כשהוא מגיע.
איך easyCoexistence עומדת בבדיקות של Meta?
לאפליקציית Meta שלה יש כתובת callback אחת לעמודים שהיא מחברת, ונקודת הקצה הזאת מבצעת את שתי הבדיקות בעצמה. היא עונה ל-GET רק כאשר hub.mode הוא subscribe והאסימון לאימות תואם, בהשוואה בזמן קבוע, ומחזירה 403 אחרת. היא קוראת כל POST כטקסט גולמי, מחשבת מחדש את X-Hub-Signature-256 עם סוד האפליקציה שלה, דוחה אי-התאמה ב-401, ועונה ל-Meta מיד ומטפלת באירוע אחרי התגובה.
איך easyCoexistence חותמת על מה שהיא מעבירה?
בחתימה משלה, מכיוון שאת כותרת Meta אפשר לבדוק רק עם סוד האפליקציה של easyCoexistence והיא אינה מועברת הלאה. כל רשומה לעמוד מחובר שיש לו נקודת קצה מוגדרת נשלחת אליה ב-POST כ-JSON, בצורת {platform, account_id, external_id, entry}, עם כותרת X-EC-Signature בצורה t=<unix>,v1=<hex>. כאן v1 הוא ה-HMAC-SHA256 של חותמת הזמן, תו נקודה והגוף הגולמי, במפתח סוד החתימה של אותו עמוד:
- הסוד מתחיל ב-whsec_ ומוצג פעם אחת בלבד, ונוצר על ידי
set_social_webhook_destinationאו PUT /channels/:id/webhook בממשק ה-Partner API המתועד. - הגדרת הכתובת מחדש יוצרת סוד חדש, וכתובת ריקה (null) מכבה את ההעברה.
- כל העברה נשלחת פעם אחת, ממתינה עד 8 שניות, בלי לעקוב אחרי הפניות, אל כתובת HTTPS שמתפענחת לכתובת IP ציבורי.
- לא נשמר עותק של האירוע, ולכן אין ממה לנסות שוב.
איך מאמתים את X-EC-Signature?
מפצלים את הכותרת ל-t ול-v1, דוחים חותמת זמן ישנה מ-5 דקות, מחשבים מחדש את ה-HMAC על t, תו נקודה והגוף הגולמי עם סוד החתימה של העמוד, ומשווים בזמן קבוע. ב-Node.js, כשהגוף נשמר כבייטים גולמיים:
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 חייב להיות ערך האתגר עצמו.
- חישוב ה-HMAC אחרי מפרסר JSON. פרסור וסידור מחדש משנים את הבייטים, ו-Meta חותם את ה-payload עם Unicode מקודד, ולכן יש לבצע hash על הגוף הגולמי.
- ביצוע העבודה לפני התשובה. Messenger מצפה ל-200 תוך 5 שניות, ושעה של כשלונות מבטלת את המינוי של האפליקציה לעמוד.
- בדיקת החתימה של Meta על אירועים מועברים. Meta חותם עם סוד האפליקציה של easyCoexistence; אירוע מועבר נושא X-EC-Signature, ונבדק במפתח סוד החתימה של העמוד.
US$ 9 עד US$ 0.75 לחיבור בחודש, פוחת ככל שמוסיפים חיבורים, עם תקופת ניסיון של 3 ימים.
שאלות נפוצות
מאיפה מגיע אסימון האימות?
אתם בוחרים אותו. זו המחרוזת שמוזנת בשדה Verify Token בעת הגדרת הוובהוקים ב-App Dashboard, או הערך שנשלח בשדה verify_token לנתיב /{app-id}/subscriptions כפרמטר.
אפשר לבדוק את האימות עם curl?
כן. מדריך Messenger של Meta שולח GET עם hub.verify_token, hub.challenge=CHALLENGE_ACCEPTED ו-hub.mode=subscribe, ונקודת קצה תקינה מחזירה את הערך CHALLENGE_ACCEPTED כתשובה.
מה קורה אם נקודת הקצה נכשלת במשך שעה?
Meta שולח התראת Webhooks Disabled ומבטל את המינוי של האפליקציה לעמוד. אחרי תיקון נקודת הקצה, יש להירשם שוב לעמוד דרך subscribed_apps ולוודא שהמינוי פעיל.
האם צריכה לי אפליקציית Meta משלי כדי לקבל את הוובהוקים של עמוד?
לא עם easyCoexistence. Meta שולח לאפליקציה שלה, והיא מעבירה את האירועים של כל עמוד, חתומים ב-X-EC-Signature, אל נקודת הקצה שאתם מגדירים.
המשיכו לקרוא
מחברים את הערוץ הראשון שלכם תוך שתי דקות.
בלי לחכות לאישורים של הפלטפורמות. מחברים את WhatsApp, Instagram, TikTok או ערוץ אחר, מבקשים מה-AI לפרסם, להשיב או להפיק דוח, ורואים אותו עובד.
- 3 ימי ניסיון חינם
- ביטול בכל עת
- רק ממשקי API רשמיים
- ניטור 24/7
נבדק ב-