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

איך מקבלים בוובהוק (Webhook) את הודעות WhatsApp ואת התגובות ברשתות החברתיות של הלקוחות שלכם

כל חיבור מקבל וובהוק משלו להודעות WhatsApp של הלקוחות או לתגובות ברשתות החברתיות, דרך ה-Partner API של easyCoexistence. הודעות WhatsApp עוברות מ-Meta ישירות לכתובת הזו, חתומות בסוד של אפליקציית ה-Tech Provider ולא בסוד שאתם מחזיקים, לכן סוד אקראי ארוך בנתיב הכתובת הוא שמאמת אותן. תגובות ו-DM מ-Instagram ומ-Facebook, וכן תגובות מ-TikTok, מועברות ברגע שהן מגיעות, וחתומות לכל חשבון בכותרת X-EC-Signature.

200 characters

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

7 days

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

AS32934

חיפושי whois לנתיבים של הרשת של Meta מציגים את הכתובות שממנן מגיעים וובהוקים של WhatsApp, ו-Meta משנה אותן מעת לעת.

3 MB

הגודל המקסימלי של ה-payload בוובהוק של WhatsApp, לפי Meta.

5 minutes

הפרש הזמן שמעבר לו יש לדחות חותמת זמן חתומה של אירוע שהועבר, כשה-HMAC מושווה בזמן קבוע.

איך לכל חיבור יש יעד משלו?

באמצעות קריאה אחת לכל משאב. למספר WhatsApp: PUT /connections/{id}/webhook עם השדה url וגם השדה verify_token, או אותו זוג כ-webhook_url ו-webhook_verify_token בסשן החיבור, כך שהמספר מנותב אליכם מהדקה הראשונה. לחשבון חברתי: PUT /channels/{id}/webhook עם השדה url, לאחר שהחשבון חובר. ערך null בשדה url באחד מהם מכבה את המסירה. שני המסלולים נבדלים בשולח ובדרך האימות:

WhatsApp numberInstagram, Facebook, TikTok
Set withwebhook_url on the session, or PUT /connections/{id}/webhookPUT /channels/{id}/webhook, after it connects
Delivered byMeta, straight to your URLeasyCoexistence, forwarding each event as it arrives
BodyMeta's webhook, unchangedplatform, account_id, external_id and the network's entry
AuthenticateA long random secret in the URL pathX-EC-Signature, keyed with the account's secret
RetriesMeta's own, for up to 7 daysNone: one attempt
Copy keptNoneNone

איך מכוונים את ההודעות של מספר לנקודת הקצה שלכם?

נותנים כתובת 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 לא הוחלה.

Node.js: Meta's handshake and the path secret
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.
A forwarded Instagram comment
{
  "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 ומעמידים את העבודה בתור.
Node.js: verifying a forwarded event
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 הזו מנפיקה סוד חדש בכל פעם שנקראת עם כתובת, והסוד הישן מפסיק לחתום מיד.

איך מגדירים

  1. 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.
  2. 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.
  3. Turn on each social accountCall PUT /channels/{id}/webhook with your URL and store the signing_secret it returns against that channel.
  4. 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

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 או ברשת חברתית מתנתקאירועי connection.* ו-channel.*: ה-payload, סיבות כמו PRIMARY_INACTIVITY, חתימת X-EC-Signature וניסיונות חוזרים במשך כ-33 שעות.איך מייבאים את היסטוריית הצ'אטים ואנשי הקשר של אפליקציית WhatsApp Business דרך ה-APIייבוא אנשי קשר ועד 180 ימים של צ'אטים ממספר ב-WhatsApp Business דרך Coexistence, כולל וובהוק (Webhook) להיסטוריה ושדה chunk_order.איך מקבלים את אסימוני ה-API של לקוחותיכם ב-WhatsApp, Instagram ו-TikTokמה קריאת פרטי הגישה מחזירה עבור מספר WhatsApp של לקוח ועבור כל חשבון רשת, שדה אחר שדה, וכיצד פועלים סיבוב האסימונים והשדה token_ready.אירועי וובהוק (Webhook) של Instagram: תגובות, תיוגים והודעות DMכך מגיעים תגובות, תיוגים והודעות DM של Instagram לנקודת הקצה שלכם כאירועי וובהוק: מה כל payload כולל, איך נחתמות המסירות ומה לבדוק.וובהוק (Webhook) של Messenger לעמודי Facebook: הודעות ואזכוריםשדות הוובהוק של עמודי Facebook להודעות Messenger ולאזכורים: מבנה ה-payload, מזהי השולחים, קבצים מצורפים ודרך המסירה לנקודת הקצה.אירועי וובהוק של תגובות ב-TikTokכך מדווח וובהוק (Webhook) comment.update של TikTok על תגובות ותשובות, מה כל אירוע כולל, וכיצד הם מגיעים לנקודת הקצה שלכם, חתומים ומיד עם הגעתם.

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

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

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

נבדק ב-