אירועי וובהוק (Webhook) של Instagram: תגובות, תיוגים והודעות DM
אירועי וובהוק של Instagram מדווחים על הפעילות בחשבון מקצועי ברגע שהיא מתרחשת: תגובות חדשות, תיוגים (@mentions) והודעות DM. Meta שולחת כל אחד מהם בבקשת POST בפורמט ה-JSON לנקודת ה-HTTPS של האפליקציה המחוברת, ומנסה שוב מסירה שנכשלה לנקודה הזו במשך עד 36 שעות. easyCoexistence מעביר כל אירוע לנקודת הקצה שלכם פעם אחת, חתום לכל חשבון בנפרד, ללא ניסיונות חוזרים. עם Instagram Login, התיוגים מגיעים בתוך התראת התגובות.
כמה זמן Meta ממשיכה לנסות מסירה שנכשלה לנקודת הקצה של האפליקציה לפני שהיא מוותרת עליה.
רוב העדכונים מאוגדים על ידי Meta למסירת וובהוק אחת, אך Meta אינה מתחייבת לכך.
הדגל ש-Meta קובעת באירועי הודעה שהחשבון עצמו שלח.
רק מדיה בחשבונות ציבוריים מפעילה התראות תגובה ותיוג.
אילו אירועים קיימים?
בחשבון מקצועי שמחובר באמצעות Instagram Login, שלושה סוגי פעילות מגיעים כאירועים:
- תגובות: תגובה חדשה על מדיה של החשבון, עם מזהה התגובה, מזהה Instagram-scoped של המחבר ושם המשתמש שלו, הטקסט, ומזהה המדיה וסוגה.
- תיוגים: עם Instagram Login הם מגיעים בתוך התראת התגובות ולא כשדה נפרד משלהם.
- הודעות DM: הודעה ישירה לחשבון, עם השולח, הנמען, חותמת זמן וההודעה עצמה, כולל טקסט, קבצים מצורפים ותשובות לסטורי.
איך האירועים מגיעים לנקודת הקצה שלכם?
Meta מעבירה וובהוקים של Instagram לאפליקציה שהחשבון חובר אליה. easyCoexistence מקבלת אותם ומעבירה כל אחד מהם לנקודת ה-HTTPS שהגדרתם לאותו חשבון, ברגע שהוא מגיע, חתום בסוד ייחודי לאותו חשבון.
מגדירים את נקודת הקצה באמצעות set_social_webhook_destination מתוך Claude או ChatGPT, או באמצעות ה-Partner API דרך PUT /channels/:id/webhook. סוד החתימה מוצג פעם אחת בלבד, הגדרה מחדש של נקודת הקצה מנפיקה סוד חדש, ושליחת null במקום כתובת ה-URL מכבה את ההעברה.
איך נראית מסירה?
בקשת POST עם גוף JSON. הגוף מכיל את השדה platform, את account_id שמחזיר list_social_accounts עבור החיבור, את השדה external_id של חשבון Instagram, והשדה entry: הרשומה של Meta לאירוע, ללא שינוי. הודעת DM מגיעה באותו אופן, עם מערך messaging במקום changes. תגובה חדשה נראית כך:
{
"platform": "instagram",
"account_id": "<ACCOUNT_ID>",
"external_id": "<INSTAGRAM_ACCOUNT_ID>",
"entry": {
"id": "<INSTAGRAM_ACCOUNT_ID>",
"time": 1793318400,
"changes": [
{
"field": "comments",
"value": {
"id": "<COMMENT_ID>",
"from": { "id": "<INSTAGRAM_SCOPED_ID>", "username": "<USERNAME>" },
"text": "<COMMENT_TEXT>",
"media": { "id": "<MEDIA_ID>", "media_product_type": "<MEDIA_PRODUCT_TYPE>" }
}
}
]
}
}איך מאמתים מסירה?
לכל מסירה מצורפת הכותרת X-EC-Signature בצורה t=<unix>,v1=<hex>. v1 הוא HMAC-SHA256 של חותמת הזמן, נקודה והגוף הגולמי של הבקשה, כאשר המפתח הוא סוד החתימה של החשבון. מחשבים אותו על הגוף הגולמי בדיוק כפי שהתקבל, משווים בזמן קבוע, ודוחים חותמת זמן מלפני יותר מ-5 דקות.
import crypto from "node:crypto";
// rawBody: the request body exactly as received, as a string
export function verify(rawBody, header, secret) {
const sig = Object.fromEntries(header.split(",").map((part) => part.split("=")));
if (!sig.t || !sig.v1) return false;
if (Math.abs(Date.now() / 1000 - Number(sig.t)) > 300) return false;
const expected = crypto
.createHmac("sha256", secret)
.update(sig.t + "." + rawBody)
.digest("hex");
return expected.length === sig.v1.length &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig.v1));
}האם מסירה נשלחת שוב?
לא על ידי easyCoexistence: ההעברה מעבירה כל אירוע פעם אחת, בזיכרון, ואינה שומרת עותק שממנו אפשר לנסות שוב. עונים מהר בתשובה 2xx ומבצעים את העבודה אחר כך, ושומרים כל מה שצריך ברגע ההגעה, מאחר ש-Meta גם אינה שומרת היסטוריה של התראות קודמות שאפשר לשאול עליה.
Meta עצמה מנסה שוב מסירה שנכשלה לאפליקציה במשך עד 36 שעות, ולכן אותו אירוע עלול לפעמים להגיע פעמיים: מזהים כפילויות לפי מזהה התגובה או לפי השדה mid של ההודעה.
מה עוד כדאי לבדוק במטפל?
כמה פרטים בנתוני Meta שמכשילים מטפל ראשון:
is_echo: הודעה עםis_echoשמוגדר true נשלחה על ידי החשבון עצמו, ולכן אין צורך לענות לה.- תשובות לסטורי: הודעת DM שעונה לסטורי נושאת את השדה
reply_to, עם המזהה והכתובת של הסטורי. - תיוגים בסטורי: מגיעים כהודעה שסוג הקובץ המצורף שלה הוא
story_mention. - time: מתי Meta שלחה את ההתראה, ולא מתי נכתבה התגובה או ההודעה. חותמת הזמן של ההודעה עצמה נמצאת ברשומת messaging שלה.
- מזהי אלבומים: אירועי תגובה אינם כוללים אותם; מחפשים את האלבום לפי מזהה התגובה.
טעויות נפוצות
- לעבוד לפני שעונים. ההעברה אינה מנסה שוב, לכן מחזירים 2xx מיד ומעבדים את האירוע אחר כך.
- אימות חתימה על ה-JSON אחרי פענוח. מחשבים את ה-HMAC על הגוף הגולמי בדיוק כפי שהתקבל.
- מענה להודעות הד. הודעה עם is_echo שמוגדר true נשלחה על ידי החשבון עצמו, ותשובה אליה פותחת לולאה.
- דילוג על זיהוי כפילויות. Meta עלולה לשלוח את אותו אירוע שוב אחרי כישלון, ולכן מזהים לפי מזהה התגובה או לפי השדה mid של ההודעה.
easyCoexistence מעבירה את התגובות, התיוגים והודעות DM של חשבון Instagram לנקודת ה-HTTPS שלכם ברגע שהם מגיעים, חתומים בסוד ייחודי לחשבון וללא עותק שנשמר בדרך. מפעילים באמצעות set_social_webhook_destination מתוך Claude או ChatGPT, או דרך ה-Partner API. המחיר נע בין US$ 9 ל-US$ 0.75 לחיבור בחודש, וככל שמוסיפים חיבורים הוא יורד, עם תקופת ניסיון של 3 ימים.
שאלות נפוצות
מה משמעות שדה time באירוע וובהוק של Instagram?
מתי Meta שלחה את ההתראה, ולא מתי נכתבה התגובה או ההודעה. חותמת הזמן של הודעת DM נמצאת ברשומת messaging שלה.
האם Meta מנסה שוב מסירות וובהוק של Instagram שנכשלו?
כן. Meta מנסה שוב מסירה שנכשלה לאפליקציה במשך עד 36 שעות, ולכן אותו אירוע עלול להגיע פעמיים לפעמים: מזהים כפילויות לפי מזהה התגובה או לפי השדה mid של ההודעה. easyCoexistence מעבירה כל אירוע לנקודת הקצה שלכם פעם אחת, ולכן עונים מהר עם תשובה 2xx.
כמה עדכונים יכולה מסירת וובהוק אחת של Instagram להכיל?
עד 1,000 כאשר Meta מאגדת אותם, אף ש-Meta אינה מתחייבת לאיגוד. עוברים על כל מערך entry ולא קוראים רק את הפריט הראשון.
האם לתיוגים יש אירוע משלהם?
לא עם Instagram Login. Meta כוללת את התיוגים בהתראת התגובות, ולכן הם מגיעים באותו מסלול כמו התגובות.
המשיכו לקרוא
מחברים את הערוץ הראשון שלכם תוך שתי דקות.
בלי לחכות לאישורים של הפלטפורמות. מחברים את WhatsApp, Instagram, TikTok או ערוץ אחר, מבקשים מה-AI לפרסם, להשיב או להפיק דוח, ורואים אותו עובד.
- 3 ימי ניסיון חינם
- ביטול בכל עת
- רק ממשקי API רשמיים
- ניטור 24/7
נבדק ב-