התחברותהתחילו תקופת ניסיון
easyCoexistence ממשקי API רשמיים

אימות וובהוק (Webhook) של Instagram: hub.challenge וגם X-Hub-Signature-256

הגדרת וובהוקים (Webhook) ב-Instagram דורשת נקודת קצה HTTPS שעונה לבקשת ה-GET לאימות של Meta. הבקשה נושאת את hub.mode שמוגדר לערך subscribe, את hub.verify_token ואת hub.challenge. נקודת הקצה בודקת את האסימון ומחזירה את האתגר. אחר כך Meta שולחת אירועי JSON החתומים בכותרת X-Hub-Signature-256 עם סוד האפליקציה, אחרי שהאפליקציה נרשמה לשדות וכל חשבון נרשם דרך subscribed_apps.

easyCoexistence מטפלת בצד של Meta: האפליקציה שלה עוברת את האימות, בודקת את X-Hub-Signature-256, רושמת כל חשבון Instagram מחובר להערות, להודעות ולאזכורים, ומעבירה את האירועים לנקודת ה-HTTPS שלכם, חתומים בכותרת X-EC-Signature עם סוד לכל חשבון, ומנטרת כל חיבור לאורך כל שעות היממה.

subscribe

הערך hub.mode תמיד מופיע בבקשת האימות של Meta.

36 hours

פרק הזמן שבו Meta מנסה שוב התראה שנכשלה, בתדירות יורדת, לפני שהיא מוותרת עליה.

15 minutes

מספר משלוחי ההודעות שנכשלו לפני ש-Meta שולחת התראה לחשבון המפתח.

1 hour

מספר משלוחי ההודעות שנכשלו לפני התראת Webhooks Disabled והסרת המנוי של האפליקציה מהחשבון.

Live

מצב האפליקציה שנדרש על ידי Meta לפני שהיא מקבלת התראות עבור חשבונות המשתמשים שלה.

איך מגדירים וובהוקים של Instagram?

בארבעה שלבים, בסדר שבו מופיע במדריך של Meta. נקודת הקצה חייבת לעבור אימות לפני שאפשר לבחור שדה כלשהו. האפליקציה חייבת להיות במצב Live כדי לקבל התראות עבור חשבונות המשתמשים שלה, ונדרש אימות עסקי לגישת ייצור.

1EndpointAn HTTPS URL with a valid certificate answers the verification GET
2App fieldsCallback URL, verify token and fields set in the App Dashboard
3Each accountPOST /<IG_ID>/subscribed_apps turns its notifications on
4TestA dashboard test, then a real event, reach the endpoint

מה כוללת בקשת האימות?

בקשת GET לכתובת ה-callback, שנשלחת בכל פעם שמוגדר מוצר Webhooks ב-App Dashboard. כשהערך של 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, והקוד צריך לקרוא אותם בשמות האלה.
The verification request and its answer
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

איפה מגדירים את ה-callback והשדות?

ב-App Dashboard, תחת Instagram ו-API setup with Instagram login, בוחרים ב-Configure Webhooks: כתובת ה-callback ואסימון האימות נכנסים שם, ושמירתם מפעילה את בקשת האימות. המוצר Instagram מתחיל עם מנוי לשדות comments, live_comments, message_reactions, messages, messaging_optins, messaging_postbacks, messaging_referral וגם messaging_seen, ואפשר לבטל רישום מכל אחד מהם דרך Manage. כפתור Test שולח התראה לדוגמה עבור שדה שנבחר.

איך בודקים את X-Hub-Signature-256?

Meta חותמת כל התראה על אירוע באמצעות HMAC-SHA256 של ה-payload, עם מפתח הסוד של האפליקציה, ושולחת את התוצאה בכותרת X-Hub-Signature-256 בתור sha256= ואחריו הערך ההקסדצימלי. המקבל מחשב את אותו HMAC על גוף הבקשה הגולמי, ומשווה אותו לכותרת בזמן קבוע. המדריך של Meta להודעות מציין שהחתימה מכסה את התוכן עם Unicode מקודד, ולכן חישוב על JSON שפוענח או סודר מחדש נותן תוצאה אחרת.

Node.js: answering verification and checking X-Hub-Signature-256
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 שמפתחו הוא הסוד הזה. בלעדיו אף אחד לא יכול לחשב את הערך הצפוי, ואף מי שמחזיק עותק של ה-payload לא יכול לזייף אחד כזה, ולכן הבדיקה שייכת לשרת שמקבל את הבקשות של Meta עבור האפליקציה. Meta מבקשת שסודות האפליקציה, אסימוני הגישה ופרטי ההזדהות יישארו מחוץ ליומנים ולפניות לתמיכה. מערכת שמקבלת אירועים שעברו דרך אפליקציה אחרת לא יכולה לבדוק את החתימה של Meta כלל, ונשענת על החתימה של אותה אפליקציה.

למה כל חשבון צריך מנוי משלו?

כי לוח הבקרה של האפליקציה קובע מה היא יכולה לקבל, וההתראות על חשבון מתחילות רק אחרי שהחשבון עצמו רשום גם הוא. ב-Instagram Login שולחים POST /<IG_ID>/subscribed_apps אל graph.instagram.com, עם אסימון הגישה של משתמש Instagram בחשבון ועם subscribed_fields שמכיל את השדות שנבחרו לאפליקציה, מופרדים בפסיקים. קריאה מוצלחת מחזירה success עם הערך true.

Subscribing one account to comments and messages
POST https://graph.instagram.com/<IG_ID>/subscribed_apps
  ?subscribed_fields=comments,messages
  &access_token=<INSTAGRAM_USER_ACCESS_TOKEN>

{ "success": true }

מה Meta עושה כשההעברות נכשלות?

היא מנסה שוב, ואז מוותרת. המדריך של Meta מבקש תשובה 200 OK לכל התראה, ומזהיר שאין ערובה לאצווה של עד 1,000 עדכונים. עדכון שנכשל נשלח שוב מיד, ואז עוד כמה פעמים בתדירות יורדת לאורך 36 שעות, ואחר כך נזנח, ולכן אותו אירוע יכול להגיע פעמיים. אירועי הודעות כפופים לכללי המסירה של Meta להודעות, שפועלים מהר יותר:

  • מצופה תשובה 200 OK תוך 5 שניות, וכשמשלוח נכשל מתבצעים כמה ניסיונות חוזרים מיידיים, ולכן יש לסנן כפילויות לפי השדה mid של ההודעה.
  • אחרי 15 דקות של כישלונות נשלחת התראה לחשבון המפתח.
  • אחרי שעה של כישלונות מופיעה התראת Webhooks Disabled, והאפליקציה מוסרת מהוובהוקים של החשבון עד שתירשם מחדש.
  • הודעות שנשלחו במהלך תקלה עשויות להגיע בסדר לא נכון, ולכן יש למיין אותן לפי חותמת הזמן.

מה לבדוק כשלא מגיע כלום?

רשימת הבדיקה של Meta לפתרון תקלות, שמכסה רוב נקודות הקצה השקטות, בסדר הבא:

  • כתובת ה-callback עברה את הבדיקה, והיא נגישה ב-HTTPS עם תעודה תקפה. תעודות חתומות עצמית אינן נתמכות.
  • האפליקציה בחרה את השדה, ויש לה רמת הגישה הנדרשת: Advanced Access עבור comments וגם live_comments.
  • ההתראות מופעלות לחשבון דרך subscribed_apps, עם אסימון מאותה הגדרת כניסה.
  • החשבון עומד בכללי השדה: התראות תגובות דורשות מדיה שבבעלות חשבון ציבורי.
  • השרת מחזיר success לפני שהוא מתחיל עבודה איטית.

למה easyCoexistence חותמת מחדש את האירועים שהועברו?

כי החתימה של Meta לא יכולה לעבור הלאה. האפליקציה של easyCoexistence מקבלת את המשלוח של Meta, בודקת את X-Hub-Signature-256 עם סוד האפליקציה שלה, עונה ל-Meta מיד, ושולחת POST לכל רשומה של חשבון מחובר אל נקודת הקצה שהוגדרה לאותו חשבון, בתוך גוף חדש עם 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_ ומוצג פעם אחת, על ידי set_social_webhook_destination או PUT /channels/:id/webhook כשמגדירים את הכתובת.
  • הגדרת הכתובת שוב יוצרת סוד חדש, וכתובת null מכבה את ההעברה.
  • כל אירוע נשלח פעם אחת, עם המתנה של עד 8 שניות, בלי לעקוב אחרי הפניות, אל כתובת HTTPS שנפתרת לכתובת IP ציבורית.
  • הסרת החיבור מבטלת את המנוי של החשבון להתראות Meta ומוחקת את נקודת הקצה והסוד שלו.
Python: checking X-EC-Signature
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 או בתוך גרשיים. Meta מצפה לערך hub.challenge עצמו כגוף התגובה, עם סטטוס 200.
  • חישוב HMAC על גוף שעבר פענוח. מפענח JSON משליך את הבייטים המדויקים ש-Meta חתמה, ולכן יש לשמור את הגוף הגולמי לחישוב ה-HMAC ולפענח אותו אחר כך.
  • רישום האפליקציה ושכחה של החשבון. עד שקריאת POST /<IG_ID>/subscribed_apps מצליחה לחשבון, לא מגיעה אליו אף התראה.
  • לתת לנקודת קצה להיכשל במשך שעה. Meta מבטלת את הוובהוקים של ההודעות ומסירה את האפליקציה מהחשבון, ואז יש לרשום אותו מחדש.
עושים את זה עם EasyCoexistence

אפשר להפעיל אותה דרך Partner API או דרך set_social_webhook_destination. US$ 9 עד US$ 0.75 לחיבור בחודש, כשהמחיר יורד ככל שמוסיפים חיבורים, ותקופת ניסיון של 3 ימים בחינם.

שאלות נפוצות

מה זה hub.challenge בוובהוקים של Instagram, ומה תפקידו?

מספר שלם ש-Meta שולחת בבקשת ה-GET לאימות. אחרי שהנקודה בודקת את hub.verify_token, היא מחזירה אותו כגוף התגובה, וזה מוכיח שהיא שולטת בכתובת.

מדוע ב-PHP שמות הפרמטרים של האימות משתנים?

PHP הופכת את הנקודות בשמות הפרמטרים לקווים תחתונים, ולכן ערכי האימות של Meta מגיעים עם קווים תחתונים, כמו hub_mode, hub_challenge ו-hub_verify_token, שהקוד צריך לקרוא.

איך מפעילים מחדש וובהוקים של Instagram אחרי ש-Meta מבטלת אותם?

מתקנים את נקודת הקצה, ואז רושמים את החשבון מחדש עם POST /<IG_ID>/subscribed_apps ועם אותם שדות.

האם אפשר להשתמש בתעודה חתומה עצמית בנקודת קצה לוובהוק?

לא. Meta אינה תומכת בתעודות חתומות עצמית: כתובת ה-callback חייבת להיות נגישה ב-HTTPS עם תעודה תקפה, וזה הפריט הראשון ברשימת הבדיקה לתקלות שמפרסמת Meta.

המשיכו לקרוא

מחברים את הערוץ הראשון שלכם תוך שתי דקות.

בלי לחכות לאישורים של הפלטפורמות. מחברים את WhatsApp, Instagram, TikTok או ערוץ אחר, מבקשים מה-AI לפרסם, להשיב או להפיק דוח, ורואים אותו עובד.

  • 3 ימי ניסיון חינם
  • ביטול בכל עת
  • רק ממשקי API רשמיים
  • ניטור 24/7

נבדק ב-