ניסיונות חוזרים, כפילויות וסדר בוובהוקים (Webhook) של WhatsApp: איך לטפל בהם
Meta מנסה שוב לשלוח וובהוק (Webhook) של WhatsApp שמחזיר תשובה שאינה HTTP 200, מיד ואחר כך בתדירות יורדת עד 7 ימים, ואז הוא נמחק. הניסיונות החוזרים מגיעים לכל אפליקציה המנויה לחשבון, ולכן כפילויות הן עניין שבשגרה. עונים מהר עם 200, מסננים כפילויות לפי מזהה ההודעה או לפי מזהה הסטטוס יחד עם הסטטוס, ומסדרים את האירועים לפי חותמות הזמן שלהם.
easyCoexistence מחברת את מספר WhatsApp Business שלכם ל-Cloud API של Meta דרך Coexistence, וסופגת את המסירות החוזרות של Meta לפני שהאוטומציות שלכם רואות אותן, כך שהודעה שנשלחה שוב לא מקבלת תשובת AI שנייה.
הזמן שבו Meta ממשיכה לנסות שוב וובהוק שלא קיבל HTTP 200, לפני שהיא מוחקת אותו.
רוב העדכונים Meta אורזת לבקשת POST אחת; Meta אינה מבטיחה אריזה כזו, ולכן יש לטפל בכל בקשה בנפרד.
הגודל המרבי של ה-payload שבקשת POST של וובהוק ב-WhatsApp יכולה להכיל.
כמה זמן easyCoexistence זוכרת כל מזהה הודעה נכנסת, כדי שהודעה שנשלחה שוב לא תפעיל אוטומציה פעמיים.
מספר הניסיונות לכל העברה אל ה-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, ומפתח שיחה בלי שדה האירוע ישמור רק את השלב הראשון של השיחה. שמרו את המפתחות עם אינדקס ייחודי, כך ששני עובדים שמטפלים באותו ניסיון חוזר לא יוכלו שניהם לזכות:
באיזה סדר מגיעים וובהוקים?
לא בהכרח בסדר שבו הדברים קרו. Meta אינה מבטיחה סדר במסמכי התיעוד שלה, מסירה שנשלחה שוב מגיעה אחרי מסירות חדשות יותר, וסטטוס יכול לדלג על שלב: Meta שולחת read בלי delivered כשהודעה נקראת ברגע שהגיעה. לכן שמרו אירועים עם שדה חותמת הזמן שלהם, השוו סטטוס לפי דירוג ולא לפי זמן הגעה, ומעדיפים הודעת לקוח מאוחרת יותר על הודעה ישנה שהגיעה באיחור. במספר שמחובר ב-Coexistence ייבוא ההיסטוריה החד-פעמי יכול לחפוף להודעות חיות סביב ההטמעה, ומזהה ההודעה הוא מה שמיישב בין השניים.
איך נראה מטפל בטוח?
ארבע פעולות: מאמתים, עונים בדיוק 200, מסננים כפילויות, ואז עובדים מתור, כך שלא נמצא שום דבר איטי בין הבקשה של Meta לתשובה שלכם. הגרסה הזו בודקת את X-Hub-Signature-256 בעזרת הסוד של אפליקציית Meta שלכם; למספר מחובר דרך easyCoexistence, Meta חותמת בעזרת הסוד של easyCoexistence, ולכן יעד ישיר מאמת את עצמו בעזרת סוד ארוך בנתיב ה-URL, או עובר להעברה מנוהלת החתומה לפי מספר.
// 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 כמפתח שני.
העברות לשרת שלכם חתומות, מונחות בתור ומנוסות שוב, וכל מספר נבדק 24/7. מ-US$ 9 ועד US$ 0.75 לכל מספר בחודש, יורד ככל שמוסיפים מספרים, עם תקופת ניסיון של 3 ימים.
שאלות נפוצות
כמה זמן כדאי לשמור את המזהים שכבר ראיתי?
לפחות 7 ימים, חלון הניסיונות החוזרים של Meta. מסירה ש-Meta מנסה שוב ביום השישי חייבת להתאים למפתח שלה, אחרת תטופל כחדשה.
מה קורה להודעות של הלקוחות שלי אם נקודת הקצה שלי לא זמינה במשך ימים?
Meta מנסה שוב עד 7 ימים, ואז הוובהוקים נמחקים. במספר שמחובר ב-Coexistence השיחות עדיין נמצאות באפליקציית WhatsApp Business בטלפון, כך שהעסק יכול לענות משם.
אפשר להפעיל מחדש וובהוקים שפספסתי?
לא מ-Meta: אין ממשק API לנתוני וובהוקים היסטוריים. ייבוא ההיסטוריה החד-פעמי של מספר שמחובר ב-Coexistence רץ רק בהטמעה, ואי אפשר לבקש אותו שוב לאותו חיבור.
האם Meta שולחת את אותו עדכון ליותר משרת אחד?
היא שולחת לכל אפליקציה המנויה לחשבון העסקי של WhatsApp לאותו שדה. עם עקיפת יעד, שדות ההודעות של המספר נשלחים לכתובת העקיפה במקום לכתובת ה-callback ברירת המחדל של אותה אפליקציה.
המשיכו לקרוא
מוכנים להתחיל?
מגדירים WhatsApp Coexistence בתוך דקות, לא חודשים. האפליקציה ממשיכה לעבוד בטלפון.
התחילו תקופת ניסיון בחינםנבדק ב-