התחברותהתחילו תקופת ניסיון
Meta Tech Provider

ניסיונות חוזרים, כפילויות וסדר בוובהוקים (Webhook) של WhatsApp: איך לטפל בהם

Meta מנסה שוב לשלוח וובהוק (Webhook) של WhatsApp שמחזיר תשובה שאינה HTTP 200, מיד ואחר כך בתדירות יורדת עד 7 ימים, ואז הוא נמחק. הניסיונות החוזרים מגיעים לכל אפליקציה המנויה לחשבון, ולכן כפילויות הן עניין שבשגרה. עונים מהר עם 200, מסננים כפילויות לפי מזהה ההודעה או לפי מזהה הסטטוס יחד עם הסטטוס, ומסדרים את האירועים לפי חותמות הזמן שלהם.

easyCoexistence מחברת את מספר WhatsApp Business שלכם ל-Cloud API של Meta דרך Coexistence, וסופגת את המסירות החוזרות של Meta לפני שהאוטומציות שלכם רואות אותן, כך שהודעה שנשלחה שוב לא מקבלת תשובת AI שנייה.

7 days

הזמן שבו Meta ממשיכה לנסות שוב וובהוק שלא קיבל HTTP 200, לפני שהיא מוחקת אותו.

1,000

רוב העדכונים Meta אורזת לבקשת POST אחת; Meta אינה מבטיחה אריזה כזו, ולכן יש לטפל בכל בקשה בנפרד.

3 MB

הגודל המרבי של ה-payload שבקשת POST של וובהוק ב-WhatsApp יכולה להכיל.

7 days

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

7 attempts

מספר הניסיונות לכל העברה אל ה-Forward URL, כל אחד ממתין 10 שניות לתשובה 2xx, על פני כ-33 שעות.

מתי Meta מנסה שוב לשלוח וובהוק של WhatsApp?

בכל פעם שהמסירה לנקודת הקצה שלכם מקבלת סטטוס HTTP שאינו 200, או שלא ניתן למסור אותה כלל. Meta מנסה מיד, ואז עוד כמה פעמים בתדירות יורדת במשך 7 הימים הבאים, ומוחקת את מה שנשאר ללא אישור אחרי כן. הניסיונות מגיעים לכל אפליקציה המנויה לחשבון העסקי של WhatsApp לאותו שדה, ולכן Meta מזהירה שהם עלולים ליצור התראות כפולות. אין ממשק API לשליפת וובהוקים שעברו, כך שמסירה שחלפו עליה 7 הימים אובדת למערכת שלכם.

למה מגיעות כפילויות גם כשהשרת תקין?

כי מסירה יכולה להצליח אצלכם ועדיין להיראות ככושלת מבחינת Meta. מטפל שמבצע את העבודה לפני שהוא עונה עלול לחרוג מזמן ההמתנה של Meta, ואז Meta מנסה שוב משהו שכבר טופל. פריסה שמפעילה מחדש את השרת באמצע בקשה, איזון עומסים שמחזיר 502 לרגע, או 201 או 204 במקום 200, נחשבים כולם לכשלים. לאריזות יש מקרה נוסף: בקשת POST אחת יכולה לכלול עדכונים רבים, ולכן פסק זמן על אריזה גדולה מחזיר את כל האריזה, כולל העדכונים שכבר טיפלתם בהם.

לפי איזה מפתח מסננים כפילויות?

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

messages[].idIncoming messages: the wamid.
statuses[].id + statusOne message has sent, delivered, read; each is its own event.
message_echoes[].idReplies the owner typed in the WhatsApp Business app.
calls[].id + eventA call's connect, statuses and terminate share the wacid.
user id + value + timestampuser_preferences: a customer can stop and resume more than once.

באיזה סדר מגיעים וובהוקים?

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

איך נראה מטפל בטוח?

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

meta-webhook.mjs: 200 first, then deduplicate (Node.js, no dependencies)
// meta-webhook.mjs: node meta-webhook.mjs (no dependencies)
import crypto from "node:crypto";
import http from "node:http";

const APP_SECRET = process.env.META_APP_SECRET; // the secret of the Meta app that subscribed
const seen = new Set(); // keys already accepted: a unique index in a database in production

// One key per thing that happened, so a redelivery maps to the same keys.
function keysOf(field, value) {
  const keys = [];
  for (const m of value.messages ?? []) keys.push(`${field}:msg:${m.id}`);
  for (const s of value.statuses ?? []) keys.push(`${field}:status:${s.id}:${s.status}`);
  for (const e of value.message_echoes ?? []) keys.push(`${field}:echo:${e.id}`);
  for (const c of value.calls ?? []) keys.push(`${field}:call:${c.id}:${c.event}`);
  return keys;
}

http.createServer((req, res) => {
  const chunks = [];
  req.on("data", (c) => chunks.push(c));
  req.on("end", () => {
    const raw = Buffer.concat(chunks);
    const got = Buffer.from(String(req.headers["x-hub-signature-256"] ?? ""));
    const want = Buffer.from("sha256=" + crypto.createHmac("sha256", APP_SECRET).update(raw).digest("hex"));
    if (req.method !== "POST" || got.length !== want.length || !crypto.timingSafeEqual(got, want)) {
      res.writeHead(401).end();
      return;
    }
    res.writeHead(200).end(); // exactly 200, before any work
    const body = JSON.parse(raw.toString("utf8"));
    for (const entry of body.entry ?? []) {
      for (const change of entry.changes ?? []) {
        for (const key of keysOf(change.field, change.value ?? {})) {
          if (seen.has(key)) continue; // a retry of something already accepted
          seen.add(key);
          // queue { key, field: change.field, value: change.value } for a worker here
          console.log("new", key);
        }
      }
    }
  });
}).listen(process.env.PORT ?? 3000);

איך easyCoexistence מטפלת בניסיונות חוזרים במספר מחובר?

בכניסה, easyCoexistence בודקת את החתימה של Meta, עונה 200 ומפעילה אוטומציות אחרי התשובה, כך ש-Meta לא תנסה שוב רק משום שתשובת AI לקחה כמה שניות. כל מזהה הודעה נכנסת נשמר 7 ימים, אורך חלון הניסיונות של Meta, והודעה שנשלחה שוב מזוהה ואינה מפעילה תשובה אוטומטית שנייה.

ביציאה ל-Forward URL שלכם, כל שינוי של Meta הופך למסירה אחת עם מזהה בשדה X-EC-Delivery שנשאר זהה בין ניסיונות ההעברה: 7 ניסיונות במשך כ-33 שעות, כשכל אחד ממתין 10 שניות לתשובה 2xx. שינוי ש-Meta עצמה שולחת שוב מועבר שוב תחת מזהה מסירה חדש, ולכן סננו גם לפי המזהים של Meta בתוך השדה value.

טעויות נפוצות

  • סינון סטטוסים לפי מזהה בלבד. sent, delivered ו-read חולקים את ה-wamid, ולכן המפתח צריך לכלול גם את הסטטוס.
  • עיבוד לפני תשובה. מטפל איטי גורם ל-Meta לנסות שוב עבודה שכבר בוצעה. מחזירים 200 קודם, ועובדים מתור.
  • החזרת 201 או 204. התיעוד של Meta מתייחס לכל סטטוס שאינו 200 ככשל מסירה ומנסה אותה שוב.
  • סינון העברות לפי X-EC-Delivery בלבד. שינוי ש-Meta שולחת שוב מגיע תחת מזהה מסירה חדש; שמרו את מזהי Meta כמפתח שני.
עושים את זה עם EasyCoexistence

העברות לשרת שלכם חתומות, מונחות בתור ומנוסות שוב, וכל מספר נבדק 24/7. מ-US$ 9 ועד US$ 0.75 לכל מספר בחודש, יורד ככל שמוסיפים מספרים, עם תקופת ניסיון של 3 ימים.

שאלות נפוצות

כמה זמן כדאי לשמור את המזהים שכבר ראיתי?

לפחות 7 ימים, חלון הניסיונות החוזרים של Meta. מסירה ש-Meta מנסה שוב ביום השישי חייבת להתאים למפתח שלה, אחרת תטופל כחדשה.

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

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

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

לא מ-Meta: אין ממשק API לנתוני וובהוקים היסטוריים. ייבוא ההיסטוריה החד-פעמי של מספר שמחובר ב-Coexistence רץ רק בהטמעה, ואי אפשר לבקש אותו שוב לאותו חיבור.

האם Meta שולחת את אותו עדכון ליותר משרת אחד?

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

המשיכו לקרוא

סטטוסי וובהוק (Webhook) של WhatsApp: נשלחה, נמסרה, נקראה ונכשלהאיך WhatsApp מדווחת מה קרה להודעה ששלחתם: מערך statuses, כל ערך סטטוס, כל שדה, והתאמה לשדה wamid ולפורמט האמיתי של Meta.למה הודעת WhatsApp נכשלה: קריאת סטטוס failed והשגיאות שלוסטטוס failed אומר ש-Meta לא הצליחה לשלוח או למסור את הודעת WhatsApp. קראו את מערך errors ואת קודי השגיאה הנפוצים, למשל 131047, ומה לעשות.וובהוק ההודעות (Webhook)כל מה שלקוח שולח מגיע בשדה הזה: מה ה-payload כולל, איך מאשרים קבלה ולמה הוא לא מגיע לספק במספר מנותב.איך הודעות WhatsApp מגיעות לשרת שלכם: ישירות או מנוהלות, ואימות החתימהישיר: Meta שולחת לשרת שלכם. מנוהל: אוטומציות עונות ועותק חתום נשלח ל-Forward URL. ה-payload, X-EC-Signature ב-Node ו-Python, וניסיונות חוזרים.אימות נקודת הקצה של וובהוק (Webhook) ב-WhatsAppMeta שולחת בקשת GET לנקודת הקצה לפני מסירת אירועים. מה נשלח, מה מחזירים ולמה תשובה שגויה נכשלת בשקט.וובהוקים של WhatsApp: ניתוב הודעות ישירות לשרת שלכםאיך וובהוקים של WhatsApp עובדים, מה Meta שולחת ואיך לנתב הודעות נכנסות ישירות לנקודת הקצה שלכם.

מוכנים להתחיל?

מגדירים WhatsApp Coexistence בתוך דקות, לא חודשים. האפליקציה ממשיכה לעבוד בטלפון.

התחילו תקופת ניסיון בחינם

נבדק ב-