איך מקבלים בוובהוק (Webhook) את הודעות WhatsApp ואת התגובות ברשתות החברתיות של הלקוחות שלכם
כל חיבור מקבל וובהוק משלו להודעות WhatsApp של הלקוחות או לתגובות ברשתות החברתיות, דרך ה-Partner API של easyCoexistence. הודעות WhatsApp עוברות מ-Meta ישירות לכתובת הזו, חתומות בסוד של אפליקציית ה-Tech Provider ולא בסוד שאתם מחזיקים, לכן סוד אקראי ארוך בנתיב הכתובת הוא שמאמת אותן. תגובות ו-DM מ-Instagram ומ-Facebook, וכן תגובות מ-TikTok, מועברות ברגע שהן מגיעות, וחתומות לכל חשבון בכותרת X-EC-Signature.
האורך המקסימלי ש-Meta מתירה לכתובת ה-callback החלופית, שמעבירה את הודעות המספר לנקודת הקצה שלכם.
כמה זמן Meta מנסה שוב וובהוק של WhatsApp שנקודת הקצה שלכם לא קיבלה, בתדירות הולכת ופוחתת, מה שעלול ליצור כפילויות.
חיפושי whois לנתיבים של הרשת של Meta מציגים את הכתובות שממנן מגיעים וובהוקים של WhatsApp, ו-Meta משנה אותן מעת לעת.
הגודל המקסימלי של ה-payload בוובהוק של WhatsApp, לפי Meta.
הפרש הזמן שמעבר לו יש לדחות חותמת זמן חתומה של אירוע שהועבר, כשה-HMAC מושווה בזמן קבוע.
איך לכל חיבור יש יעד משלו?
באמצעות קריאה אחת לכל משאב. למספר WhatsApp: PUT /connections/{id}/webhook עם השדה url וגם השדה verify_token, או אותו זוג כ-webhook_url ו-webhook_verify_token בסשן החיבור, כך שהמספר מנותב אליכם מהדקה הראשונה. לחשבון חברתי: PUT /channels/{id}/webhook עם השדה url, לאחר שהחשבון חובר. ערך null בשדה url באחד מהם מכבה את המסירה. שני המסלולים נבדלים בשולח ובדרך האימות:
| WhatsApp number | Instagram, Facebook, TikTok | |
|---|---|---|
| Set with | webhook_url on the session, or PUT /connections/{id}/webhook | PUT /channels/{id}/webhook, after it connects |
| Delivered by | Meta, straight to your URL | easyCoexistence, forwarding each event as it arrives |
| Body | Meta's webhook, unchanged | platform, account_id, external_id and the network's entry |
| Authenticate | A long random secret in the URL path | X-EC-Signature, keyed with the account's secret |
| Retries | Meta's own, for up to 7 days | None: one attempt |
| Copy kept | None | None |
איך מכוונים את ההודעות של מספר לנקודת הקצה שלכם?
נותנים כתובת HTTPS שהנתיב שלה מכיל סוד אקראי ארוך, יחד עם verify_token: השדה webhook_verify_token בסשן חיבור, באורך של בין 8 ל-200 תווים, או השדה verify_token בקריאת PUT. Meta בודקת את הכתובת מיד בבקשת GET שנושאת את hub.mode=subscribe, את hub.verify_token ואת השדה hub.challenge. נקודת הקצה שלכם חייבת להחזיר את הערך של hub.challenge כשהאסימון תואם. אם לחיצת היד הזו נכשלת, הקריאה PUT מחזירה 502 meta_rejected עם ההודעה של Meta עצמה. בסשן חיבור המספר עדיין מתחבר, והשדה last_error של הסשן מסביר למה כתובת ה-URL לא הוחלה.
import express from "express";
import { timingSafeEqual } from "node:crypto";
const PATH_SECRET = process.env.WA_PATH_SECRET; // the random part of webhook_url
const VERIFY_TOKEN = process.env.WA_VERIFY_TOKEN; // the verify token you sent
const app = express();
function same(a, b) {
const x = Buffer.from(String(a)), y = Buffer.from(String(b));
return x.length === y.length && timingSafeEqual(x, y);
}
// Meta's handshake, run when the destination is set
app.get("/wa/:secret", (req, res) => {
if (!same(req.params.secret, PATH_SECRET)) return res.sendStatus(404);
if (req.query["hub.mode"] !== "subscribe" || !same(req.query["hub.verify_token"], VERIFY_TOKEN)) {
return res.sendStatus(403);
}
res.send(req.query["hub.challenge"]);
});
// Messages, echoes and the one-time import; payloads reach 3 MB
app.post("/wa/:secret", express.json({ limit: "4mb" }), (req, res) => {
if (!same(req.params.secret, PATH_SECRET)) return res.sendStatus(404);
res.sendStatus(200); // answer first: Meta retries for up to 7 days
enqueue(req.body); // deduplicate on each message id before acting
});למה אי אפשר לבדוק את החתימה של Meta, ומה מחליף אותה?
Meta חותמת כל מסירה בכותרת X-Hub-Signature-256, שהיא HMAC-SHA256 של המטען עם המפתח App Secret של האפליקציה המקבלת. במספרים של הלקוחות שלכם האפליקציה היא אפליקציית ה-Tech Provider של easyCoexistence, והסוד שלה לעולם אינו משותף, ולכן הכותרת לא ניתנת לאימות בצדכם. הסוד האקראי הארוך בנתיב הכתובת משמש במקומה כפרטי הזיהוי: משווים אותו בזמן קבוע ודוחים כל דבר אחר. כשכבה שנייה, מאשרים את הנתיבים הרשומים למערכת האוטונומית AS32934 של Meta ומרעננים את הרשימה, כי Meta משנה את כתובות ה-IP שלה מעת לעת.
אילו וובהוקים של WhatsApp מגיעים לכתובת שלכם?
השדות ש-Meta מאפשרת לכתובת callback חלופית לשאת: messages, עבור מה שהלקוחות שולחים וסטטוס של מה ששלחתם; smb_message_echoes, עבור מה שהעסק שולח מאפליקציית WhatsApp Business; וההיסטוריה של הייבוא החד-פעמי, יחד עם smb_app_state_sync. Meta לעולם לא שולחת וובהוקים של תבניות, או וובהוקים של חשבון כמו account_update, לכתובת העוקפת. הם מגיעים במקום זאת ל-callback של easyCoexistence, ולכן את סקירת התבניות קוראים בפולינג, ודחייה מגיעה אליכם כאירוע סטטוס.
- היעד נקבע בחשבון ה-WhatsApp Business, ולכן שני מספרים באותו חשבון חולקים אותו: מנתבים לפי השדה value.metadata.
phone_number_id. - המדיה מגיעה כמזהה; את הקובץ מביאים מ-Meta עם האסימון של הלקוח, מקריאת ה-credentials.
- המטענים יכולים להגיע עד 3 MB, לכן העלו כל מגבלת גודל של גוף הבקשה שמוגדרת מתחת לזה.
איך נראה אירוע חברתי שהועבר?
POST עם Content-Type application/json וכותרת X-EC-Signature, ובו ארבעה מפתחות: platform; account_id, מזהה הערוץ שבו משתמש ה-Partner API; external_id, המזהה של החשבון ברשת; והשדה entry. באינסטגרם ובפייסבוק, השדה entry הוא ה-entry של Meta כמו שהוא, עם changes לתגובות ולאזכורים, ועם messaging ל-DM. בטיקטוק הוא מכיל את אירוע comment.update עם התוכן מפוענח, ואת השדות comment_id, video_id וגם parent_comment_id, כמחרוזות, כך שמזהים של 64 סיביות לא מעוגלים.
- חשבונות אינסטגרם רשומים לתגובות, להודעות ולאזכורים; דפי פייסבוק ל-feed, להודעות ולאזכור; טיקטוק שולח comment.update.
- easyCoexistence לא מקבלת אירועי תגובות מ-YouTube או מ-LinkedIn: הקריאה שלהם עונה 400
not_supported, והתגובות שלהם נקראות דרך ה-API של כל רשת, עם פרטי הגישה. - ההעברות לא נושאות כותרת X-EC-Event או X-EC-Delivery, לכן מבטלים כפילויות לפי המזהים של הרשת עצמה, כמו מזהה תגובה או message mid.
{
"platform": "instagram",
"account_id": "<CHANNEL_ID>",
"external_id": "<INSTAGRAM_ACCOUNT_ID>",
"entry": {
"id": "<INSTAGRAM_ACCOUNT_ID>",
"time": 1793440800,
"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, שלב אחר שלב?
עם signing_secret שהחזירה הקריאה PUT /channels/{id}/webhook, שמוצג פעם אחת בלבד וייחודי לאותו חשבון. הכותרת נראית כך: t=<unix>,v1=<hex>. ואז, לכל מסירה:
- קוראים את גוף הבקשה הגולמי כבייטים, לפני כל פענוח JSON.
- מפצלים את הכותרת לפי פסיקים: את t, שהוא זמן Unix בשניות, ואת v1, שהוא תקציר hex.
- דוחים את המסירה אם t רחוק יותר מ-5 דקות מהשעון שלכם.
- מחשבים HMAC-SHA256 על t, נקודה והגוף הגולמי, עם הסוד של אותו חשבון, ומקבלים ערך hex.
- משווים אותו ל-v1 בזמן קבוע, ואז עונים 2xx ומעמידים את העבודה בתור.
import express from "express";
import { createHmac, timingSafeEqual } from "node:crypto";
const app = express();
const secrets = new Map(); // channel id -> signing_secret, kept in your database
app.post("/hooks/social", express.raw({ type: "application/json" }), (req, res) => {
const sig = Object.fromEntries(
(req.get("X-EC-Signature") ?? "").split(",").map((part) => part.split("=", 2)),
);
if (!/^\d+$/.test(sig.t ?? "") || Math.abs(Date.now() / 1000 - Number(sig.t)) > 300) {
return res.sendStatus(401); // missing or stale timestamp
}
let event;
try {
event = JSON.parse(req.body.toString("utf8")); // platform, account_id, external_id, entry
} catch {
return res.sendStatus(400);
}
const secret = secrets.get(event.account_id);
if (!secret || !sig.v1) return res.sendStatus(401);
const expected = createHmac("sha256", secret)
.update(sig.t + ".")
.update(req.body) // the raw bytes, exactly as they arrived
.digest("hex");
if (expected.length !== sig.v1.length ||
!timingSafeEqual(Buffer.from(expected), Buffer.from(sig.v1))) {
return res.sendStatus(401);
}
res.sendStatus(204); // one attempt and no retries: acknowledge, then work
enqueue(event);
});מה קורה כשאין יעד מוגדר?
שום דבר לא מגיע אליכם, ושום דבר לא ממתין לשליחה מאוחר יותר. מספר בלי השדה webhook_url חוזר לכתובת ה-callback של easyCoexistence, שם ההודעות שלו נזרקות בלי לשמור אותן, והוא לא מקבל ייבוא של היסטוריית צ'אט, שמתבקש רק כשקיים יעד. חשבון חברתי בלי יעד לא מועבר: האירועים שלו עדיין מגיעים לאפליקציה של easyCoexistence, אבל אף אחד מהם לא נשמר בשבילכם. הגדירו כל יעד לפני שאתם צריכים את התעבורה.
מה קורה ליעד כשחיבור נופל או מוסר?
מספר שומר את היעד שלו ברשומה. כשמספר שנפל מתחבר מחדש, easyCoexistence מגדירה שוב את הכתובת שלכם מול Meta, וכך גם כשמספר מושעה חוזר. הסרת חשבון חברתי מנקה את היעד ואת הסוד שלו, ולכן אחרי שהוא מתחבר מחדש, קוראים שוב לקריאה PUT /channels/{id}/webhook ושומרים את הסוד החדש. הקריאה PUT הזו מנפיקה סוד חדש בכל פעם שנקראת עם כתובת, והסוד הישן מפסיק לחתום מיד.
איך מגדירים
- Put a secret in the URLChoose an HTTPS URL whose path holds a long random string, 200 characters or fewer in all, and make its GET answer Meta's hub.challenge.
- Route the number's messagesSend webhook_url and webhook_verify_token on the connect session, or PUT /connections/{id}/webhook once the number is connected.
- Turn on each social accountCall PUT /channels/{id}/webhook with your URL and store the signing_secret it returns against that channel.
- Verify, then acknowledgeCheck the path secret on WhatsApp deliveries and X-EC-Signature on forwarded ones, answer 2xx at once, then process from a queue.
טעויות נפוצות
- בדיקת הכותרת X-Hub-Signature-256 במסירות ה-WhatsApp של הלקוחות שלכם. Meta מחשבת אותה עם סוד האפליקציה של easyCoexistence, שלעולם אינו משותף, ולכן הבדיקה לא תעבור לעולם; מאמתים עם הסוד בנתיב הכתובת.
- אימות X-EC-Signature על JSON שפוענח כבר. ה-HMAC מכסה את הגוף הגולמי בייט אחר בייט, וסידור מחדש משנה את הבייטים, ולכן מאמתים לפני הפענוח.
- שימוש בסוד אחד לכל הערוצים. כל חשבון חברתי חותם בסוד משלו, ואירועי סטטוס בסוד אחר, ולכן מחפשים את הסוד לפי השדה account_id.
- ביצוע עבודה איטית לפני מענה לאירוע שהועבר. הוא נשלח פעם אחת, מחכה 8 שניות לתשובה שלכם ולעולם לא נשלח שוב, ולכן עונים 2xx קודם, ומעבדים אחר כך.
easyCoexistence מנתבת את ההודעות של כל מספר לקוח מ-Meta ישירות לשרת שלכם, ומעבירה תגובות ו-DM מ-Instagram ומ-Facebook, וכן תגובות מ-TikTok, לנקודת הקצה שלכם ברגע שהן מגיעות, חתומות לכל חשבון, בלי לשמור עותק, וכל חיבור מנוטר 24/7. בין US$ 9 ל-US$ 0.75 לחיבור בחודש, שיורד ככל שמוסיפים חיבורים, עם תקופת ניסיון של 3 ימים.
שאלות נפוצות
האם אפשר לאמת את החתימה של Meta על ההודעות של הלקוחות שלכם ב-WhatsApp?
לא. Meta חותמת אותן עם הסוד של אפליקציית ה-Tech Provider של easyCoexistence, שלעולם אינו משותף. מאמתים עם הסוד הארוך והאקראי בנתיב הכתובת שלכם, ואופציונלית עם טווחי ה-IP של Meta.
האם חיבורי YouTube ו-LinkedIn מעבירים אירועי תגובה?
לא. easyCoexistence לא מקבלת אירועי תגובה מאף אחד מהם, ולכן הקריאה PUT /channels/{id}/webhook עונה 400 not_supported. קוראים את התגובות שלהם דרך ה-API של כל רשת, עם פרטי הגישה של הערוץ.
האם אירועים חברתיים שהועברו מנוסים מחדש אם השרת שלי למטה?
לא. כל אירוע נשלח פעם אחת, ולא נשמר ממנו עותק. מסירות WhatsApp שונות, כי Meta עצמה מנסה אותן שוב עד 7 ימים.
האם הודעות עוברות דרך easyCoexistence?
לא ב-WhatsApp: Meta מעבירה את ההודעות של מספר ישירות לוובהוק שהגדרתם. תגובות והודעות ישירות מהרשתות החברתיות מועברות לנקודת הקצה שלכם ברגע שהן מגיעות, חתומות לכל חשבון, בלי שמירת עותק.
המשיכו לקרוא
מחברים את הערוץ הראשון שלכם תוך שתי דקות.
בלי לחכות לאישורים של הפלטפורמות. מחברים את WhatsApp, Instagram, TikTok או ערוץ אחר, מבקשים מה-AI לפרסם, להשיב או להפיק דוח, ורואים אותו עובד.
- 3 ימי ניסיון חינם
- ביטול בכל עת
- רק ממשקי API רשמיים
- ניטור 24/7
נבדק ב-