איך הודעות WhatsApp מגיעות לשרת שלכם: ישירות או מנוהלות, ואימות החתימה
לכל מספר שמחובר דרך easyCoexistence יש מצב אחד להודעות נכנסות. ישירות למערכת שלכם (ישיר): Meta שולחת את הוובהוק (Webhook) שלה לנקודת הקצה ה-HTTPS שלכם, סוד בכתובת ה-URL הוא פרטי הזיהוי, והאוטומציות כבויות. דרך easyCoexistence (מנוהל): Meta שולחת ל-easyCoexistence, האוטומציות יכולות לענות, וכתובת Forward URL אופציונלית מקבלת את הערך המקורי של Meta יחד עם פרטי החיבור, חתום ב-X-EC-Signature כדי שתוכלו לאמת אותו.
ניסיונות לכל משלוח מועבר, במרווחים של 1 min, 5 min, 30 min, 2 h, 6 h ו-24 h, כ-33 שעות בסך הכול.
כמה זמן כל ניסיון העברה ממתין לתשובה 2xx לפני שהוא נחשב ככישלון.
הגבלה מומלצת על גיל ה-t בחתימה; הניסיונות חתומים מחדש, כך שמשלוחים אמיתיים נשארים בתוך הטווח.
כמה זמן Meta מנסה שוב וובהוק ישיר שקיבל כל תשובה חוץ מ-HTTP 200, וזה יכול לגרום לחזרה על הודעות.
ה-payload הגדול ביותר ש-Meta שולחת בוובהוק, כולל חלקי ההיסטוריה.
יומני הרצה שנשמרים למספר מנוהל, כולל טקסט הודעות ותשובות; טקסט ההודעות עצמו נשמר 30, 90 או 365 ימים, לבחירתכם.
מה ההבדל בין ישיר למנוהל?
איפה Meta שולחת את הוובהוקים של הודעות המספר. במצב מנוהל, שמוצג כ-Through easyCoexistence, Meta שולחת ל-easyCoexistence, שבודקת את החתימה של Meta, מפעילה את האוטומציות שלכם, שומרת את הצ'אטים עבור Conversations ואם הגדרתם Forward URL, מעבירה לכם כל שינוי של Meta חתום בסוד שרק אתם מחזיקים. במצב ישיר, שמוצג כ-Straight to your system, easyCoexistence מגדירה את נקודת הקצה ה-HTTPS שלכם כיעד הוובהוק בחשבון ה-WhatsApp Business של המספר, כך ש-Meta שולחת אליכם ישירות, וההודעות לא מגיעות ל-easyCoexistence בכלל.
וובהוקים תפעוליים, כמו account_update ושינויי איכות שמאחורי הניטור, נשארים אצל easyCoexistence בשני המצבים, ולכן ההתראות ממשיכות לעבוד בכל מקרה.
| Managed: Through easyCoexistence | Direct: Straight to your system | |
|---|---|---|
| Meta delivers to | easyCoexistence, which verifies Meta's signature | Your HTTPS endpoint |
| Automations | Run on the number | Off |
| Your copy | Optional Forward URL, one Meta change per POST | Meta's envelope, unchanged |
| Proof it is genuine | X-EC-Signature, HMAC-SHA256 with the number's secret | A long random secret in the URL path |
| Failed deliveries | 7 attempts over about 33 hours | Meta retries for up to 7 days |
| History import | Not requested | Requested when saved within 24 hours of connecting |
| Kept by easyCoexistence | Message text 30, 90 or 365 days, run logs 30 days | Nothing |
איך מחליפים מספר בין השניים?
בעמוד המספר, הכרטיס Where incoming messages go מציג את המצב כשתי אפשרויות, Through easyCoexistence ו-Straight to your system. שמירת יעד וובהוק, בכרטיס Route incoming messages to your own וובהוק או עם set_webhook_destination, הופכת את המספר לישיר. בחירה ב-Through easyCoexistence מוחקת מיד את היעד הזה ב-Meta, ולכן הוסיפו את אותה כתובת כ-Forward URL כדי להמשיך לקבל. העברות בתור נמחקות כשמספר יוצא ממצב מנוהל, ומספרים שחוברו בלי כתובת וובהוק מתחילים במצב מנוהל.
מה-AI שלכם, set_inbound_mode מחליף את המצב ומגדיר את ההעברה בקריאה אחת, ומחזיר את סוד ההעברה פעם אחת:
// set_inbound_mode arguments
{
"connection_id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f",
"mode": "managed",
"forward_url": "https://agent.example.com/ec/forward"
}
// result: forward_secret is shown once
{
"connection_id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f",
"mode": "managed",
"forward_url": "https://agent.example.com/ec/forward",
"forward_secret": "whsec_Qm9vbXRoZXNlY3JldHNhcmVmYWtlMTIz",
"secret_note": "Shown once. Verify X-EC-Signature: t=<unix>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\"> with it; the body's value is Meta's original payload.",
"direct_destination": null
}מה מכיל POST מועבר?
שינוי אחד של Meta לכל בקשה, עטוף, במקום המעטפת object, entry ו-changes של Meta. id הוא מזהה המשלוח, שחוזר ב-X-EC-Delivery ונשאר יציב בין ניסיונות חוזרים. event הוא שם השדה של Meta, messages, smb_message_echoes, history או smb_app_state_sync, וחוזר ב-X-EC-Event. received_at הוא הזמן שבו easyCoexistence קיבלה את השינוי מ-Meta, connection מזהה את המספר, ו-value הוא בדיוק מה ש-Meta שלחה, ולכן קוד ניתוח שנכתב עבור המטען של Meta עובד עליו. סטטוסי משלוח מגיעים בתוך אירועי messages, תחת value.statuses.
POST /ec/forward HTTP/1.1
Content-Type: application/json
User-Agent: easyCoexistence-forward/1
X-EC-Event: messages
X-EC-Delivery: 8c1d7e52-0f4b-4a3e-9d61-2b7f5a9e0c13
X-EC-Signature: t=1794405732,v1=<64 hex characters>
{
"id": "8c1d7e52-0f4b-4a3e-9d61-2b7f5a9e0c13",
"event": "messages",
"received_at": "2026-11-11T14:02:11.482Z",
"connection": {
"id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f",
"phone": "+1 631-555-0142",
"phone_number_id": "106540352242922",
"waba_id": "102290129340398",
"external_ref": null
},
"value": {
"messaging_product": "whatsapp",
"metadata": { "display_phone_number": "16315550142", "phone_number_id": "106540352242922" },
"contacts": [{ "profile": { "name": "Ana Souza" }, "wa_id": "5511987654321", "user_id": "BR.13491208655302741918" }],
"messages": [{
"from": "5511987654321",
"from_user_id": "BR.13491208655302741918",
"id": "wamid.HBgNNTUxMTk4NzY1NDMyMRUCABIYFjNFQjBDNzE4RjQ2QjI5RDkxQTNFAA==",
"timestamp": "1794405731",
"type": "text",
"text": { "body": "Do you deliver on Sundays?" }
}]
}
}איך מאמתים את X-EC-Signature ב-Node.js?
קוראים את הכותרת כ-t=<unix seconds>,v1=<64 hex characters>. דוחים t שמרחיק יותר מ-5 דקות מהשעון שלכם, מחשבים HMAC-SHA256 על t, נקודה והגוף הגולמי, עם כל סוד ההעברה כטקסט UTF-8, ומשווים את התוצאה ל-v1 בזמן קבוע. רק אז מנתחים את ה-JSON. עונים 2xx תוך 10 שניות ומבצעים את העבודה אחר כך, וזוכרים את מזהי המשלוח שקיבלתם, כדי שניסיון חוזר לא יעובד פעמיים.
// forward-receiver.mjs: node forward-receiver.mjs (no dependencies)
import crypto from "node:crypto";
import http from "node:http";
const SECRET = process.env.EC_FORWARD_SECRET; // the whole whsec_... string is the HMAC key
const taken = new Set(); // delivery ids already accepted: use a database in production
export function verifyEcSignature(raw, header, secret = SECRET, maxAgeSec = 300) {
const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(String(header ?? "").trim());
if (!m || !secret) return false;
if (Math.abs(Math.floor(Date.now() / 1000) - Number(m[1])) > maxAgeSec) return false;
const mac = crypto.createHmac("sha256", secret).update(`${m[1]}.`).update(raw).digest();
return crypto.timingSafeEqual(mac, Buffer.from(m[2], "hex"));
}
http.createServer((req, res) => {
const chunks = [];
req.on("data", (c) => chunks.push(c));
req.on("end", () => {
const raw = Buffer.concat(chunks);
if (req.method !== "POST" || !verifyEcSignature(raw, req.headers["x-ec-signature"])) {
res.writeHead(401).end();
return;
}
res.writeHead(200).end(); // a 2xx within 10 s, before any work
const d = JSON.parse(raw.toString("utf8"));
if (taken.has(d.id)) return; // a retry of a delivery already accepted
taken.add(d.id);
// d.event is the Meta field (messages, smb_message_echoes, history, smb_app_state_sync)
// d.value is Meta's change value, unchanged; queue it for your worker here.
console.log(d.event, d.connection.phone_number_id, Object.keys(d.value));
});
}).listen(process.env.PORT ?? 3000);איך מאמתים בפייתון?
אותן ארבע בדיקות עם הספרייה הסטנדרטית: תבנית מחמירה לכותרת, גיל ה-t, hmac.new על t, נקודה והבייטים הגולמיים, ו-hmac.compare_digest. ב-FastAPI הגוף הגולמי מגיע מ-await request.body(), ו-BackgroundTasks מריץ את העבודה אחרי שה-200 נשלח. ב-Flask משתמשים ב-request.get_data(), ולעולם לא בונים מחדש את הגוף עם json.dumps, כי ברירת המחדל של פייתון מוסיפה רווחים והחתימה כבר לא תואמת.
# forward_receiver.py: pip install fastapi uvicorn, then uvicorn forward_receiver:app
import hashlib, hmac, json, os, re, time
from fastapi import BackgroundTasks, FastAPI, Request, Response
app = FastAPI()
SECRET = os.environ["EC_FORWARD_SECRET"].encode() # the whole whsec_... string, as bytes
SIGNATURE = re.compile(r"t=([0-9]+),v1=([0-9a-f]{64})")
taken = set() # delivery ids already accepted: use a database in production
def verify_ec_signature(raw: bytes, header: str, max_age: int = 300) -> bool:
m = SIGNATURE.fullmatch(header.strip())
if not m or abs(int(time.time()) - int(m[1])) > max_age:
return False
mac = hmac.new(SECRET, m[1].encode() + b"." + raw, hashlib.sha256).hexdigest()
return hmac.compare_digest(mac, m[2])
def process(delivery: dict) -> None:
if delivery["id"] in taken: # a retry of a delivery already accepted
return
taken.add(delivery["id"])
print(delivery["event"], delivery["connection"]["phone_number_id"], list(delivery["value"]))
@app.post("/ec/forward")
async def forward(request: Request, tasks: BackgroundTasks):
raw = await request.body()
if not verify_ec_signature(raw, request.headers.get("x-ec-signature", "")):
return Response(status_code=401)
tasks.add_task(process, json.loads(raw)) # runs after the 200 goes out
return Response(status_code=200)איך משלוחים שנכשלו מנוסים שוב?
משלוח נחשב כמועבר כשנקודת הקצה שלכם עונה כל תשובה 2xx תוך 10 שניות. כל דבר אחר, פסק זמן, 4xx, 5xx או הפניה שאינה נעקבת, מתזמן את הניסיון הבא בעוד כ-1 דקה, 5 דקות, 30 דקות, 2 שעות, 6 שעות ו-24 שעות, ואחרי הניסיון השביעי המשלוח נזנח. כל ניסיון נחתם מחדש עם t חדש, וכתובת ה-URL חייבת להיות HTTPS ציבורי, נבדקת בשמירה ושוב לפני כל שליחה. המשלוחים יוצאים מהישן לחדש, אבל ניסיון חוזר עלול להגיע אחרי משלוחים חדשים יותר, לכן מיינו לפי חותמות הזמן של Meta.
ביעד ישיר Meta עושה את הניסיונות החוזרים: כל דבר חוץ מ-HTTP 200 מנוסה שוב בתדירות יורדת עד 7 ימים, וניסיונות כאלה יכולים לחזור על הודעה. סננו כפילויות לפי מזהה ההודעה של Meta בשני המצבים, כי שינוי ש-Meta שולחת שוב מועבר שוב תחת מזהה משלוח חדש.
איך נקודת קצה ישירה יודעת ש-POST הוא אמיתי?
לא לפי X-Hub-Signature-256. Meta חותמת עם סוד האפליקציה של האפליקציה שהמינוי שייך לה, שבמקרה של מספר שחובר כאן הוא של easyCoexistence ואינו משותף, ולכן בדיקת הכותרת הזו עם סוד האפליקציה שלכם ב-Meta דוחה משלוחים אמיתיים. אסימון האימות מוכיח את נקודת הקצה רק פעם אחת, בזמן לחיצת היד GET של Meta. מה שכן עובד במקום זה:
- שימו 32 תווים אקראיים או יותר בנתיב כתובת ה-callback ודחו בקשות בלעדיהם; כדי לסובב, שמרו כתובת חדשה.
- השתמשו במקלט גנרי, כמו צומת ה-Webhook של n8n, ולא בטריגר WhatsApp שמצפה לאפליקציית Meta משלכם.
- הורידו מדיה לפי מזהה מ-Meta עם האסימון של המספר, כך שמזהה מזויף פשוט נכשל.
- בשרתים עצמאיים אפשר לאפשר, לבחירתכם, רק את הרשת של Meta, כלומר הנתיבים ש-AS32934 מכריז עליהם.
- או עברו למנוהל עם Forward URL, שבו X-EC-Signature מוכיח כל POST.
טעויות נפוצות
- להפנות קוד שנכתב למעטפת של Meta ל-Forward URL בלי לשנות אותו. העברה נושאת שינוי אחד: קראו את event ואת value, לא את object, entry ו-changes.
- לחכות ל-X-EC-Event מסוג statuses. סטטוסי המשלוח מגיעים בתוך אירועי messages, ב-value.statuses, ותשובות שנכתבו באפליקציה מגיעות כ-smb_message_echoes.
- לבצע את העבודה לפני שעונים. העברה ממתינה 10 שניות, ואז אותו משלוח חוזר עם t חדש; ענו 2xx קודם ועבדו מתור.
- לעבור למנוהל ולהניח שהכתובת הישנה עדיין מקבלת. יעד הישיר נמחק באותו רגע; העבירו forward_url באותה קריאה של set_inbound_mode.
easyCoexistence מחברת מספר של אפליקציית WhatsApp Business ל-Cloud API של Meta דרך Coexistence, ומאפשרת לבחור, לכל מספר, לאן ההודעות שלו הולכות: ישירות מ-Meta לשרת שלכם, או דרך easyCoexistence, כדי שאוטומציות יוכלו לענות ועותק חתום יגיע ל-Forward URL. ניטור והתראות עובדים בשני המצבים. מ-US$ 9 עד US$ 0.75 למספר בחודש, ויורד ככל שמוסיפים מספרים, עם 3 הימים הראשונים בחינם.
שאלות נפוצות
האם השרת שלי רואה מה שענתה אוטומציה?
לא את הטקסט. Meta מדווחת על שליחות API כסטטוסים (sent, delivered, read) בתוך אירועי messages, עם מזהה ההודעה; הטקסט עצמו נמצא ביומן ההרצה של האוטומציה, שנשמר 30 ימים בלשונית Runs, וב-Conversations למשך הזמן שבחרתם.
איך מסובבים את סוד ההעברה?
לוחצים על New secret בעמוד המספר, או קוראים ל-set_inbound_mode עם rotate_secret שמוגדר ל-true. הסוד החדש מוצג פעם אחת וחותם על הכול מאותו רגע, כולל ניסיונות חוזרים של משלוחים ישנים, לכן עדכנו את השרת שלכם מיד.
האם Forward URL צריך את לחיצת היד GET של Meta?
לא. רק יעד ישיר נקרא על ידי Meta וצריך להחזיר את hub.challenge. Forward URL נקרא על ידי easyCoexistence ומקבל רק POST חתומים.
האם למספר יכול להיות יעד ישיר וגם Forward URL באותו זמן?
לא. Forward URL פועל רק בזמן שהמספר מנוהל, ושמירת יעד ישיר הופכת אותו לישיר. Forward URL וסוד שלו נשמרים, ולכן חזרה למנוהל ממשיכה את ההעברה.
המשיכו לקרוא
מוכנים להתחיל?
מגדירים WhatsApp Coexistence בתוך דקות, לא חודשים. האפליקציה ממשיכה לעבוד בטלפון.
התחילו תקופת ניסיון בחינםנבדק ב-