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

איך הודעות WhatsApp מגיעות לשרת שלכם: ישירות או מנוהלות, ואימות החתימה

לכל מספר שמחובר דרך easyCoexistence יש מצב אחד להודעות נכנסות. ישירות למערכת שלכם (ישיר): Meta שולחת את הוובהוק (Webhook) שלה לנקודת הקצה ה-HTTPS שלכם, סוד בכתובת ה-URL הוא פרטי הזיהוי, והאוטומציות כבויות. דרך easyCoexistence (מנוהל): Meta שולחת ל-easyCoexistence, האוטומציות יכולות לענות, וכתובת Forward URL אופציונלית מקבלת את הערך המקורי של Meta יחד עם פרטי החיבור, חתום ב-X-EC-Signature כדי שתוכלו לאמת אותו.

7 attempts

ניסיונות לכל משלוח מועבר, במרווחים של 1 min, 5 min, 30 min, 2 h, 6 h ו-24 h, כ-33 שעות בסך הכול.

10 s

כמה זמן כל ניסיון העברה ממתין לתשובה 2xx לפני שהוא נחשב ככישלון.

5 min

הגבלה מומלצת על גיל ה-t בחתימה; הניסיונות חתומים מחדש, כך שמשלוחים אמיתיים נשארים בתוך הטווח.

7 days

כמה זמן Meta מנסה שוב וובהוק ישיר שקיבל כל תשובה חוץ מ-HTTP 200, וזה יכול לגרום לחזרה על הודעות.

3 MB

ה-payload הגדול ביותר ש-Meta שולחת בוובהוק, כולל חלקי ההיסטוריה.

30 days

יומני הרצה שנשמרים למספר מנוהל, כולל טקסט הודעות ותשובות; טקסט ההודעות עצמו נשמר 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 easyCoexistenceDirect: Straight to your system
Meta delivers toeasyCoexistence, which verifies Meta's signatureYour HTTPS endpoint
AutomationsRun on the numberOff
Your copyOptional Forward URL, one Meta change per POSTMeta's envelope, unchanged
Proof it is genuineX-EC-Signature, HMAC-SHA256 with the number's secretA long random secret in the URL path
Failed deliveries7 attempts over about 33 hoursMeta retries for up to 7 days
History importNot requestedRequested when saved within 24 hours of connecting
Kept by easyCoexistenceMessage text 30, 90 or 365 days, run logs 30 daysNothing

איך מחליפים מספר בין השניים?

בעמוד המספר, הכרטיס 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 and result
// 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.

A forwarded messages event: headers and body
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.js, no dependencies)
// 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 (FastAPI)
# 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

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 וסוד שלו נשמרים, ולכן חזרה למנוהל ממשיכה את ההעברה.

המשיכו לקרוא

בניית סוכן AI ל-WhatsApp ב-Node.js וב-Python על מספר Coexistenceקוד Node.js ו-Python לסוכן AI ב-WhatsApp על מספר Coexistence: אימות אירועים חתומים, השהיה כשאדם עונה, דילוג על כפילויות ובדיקת חלון 24 שעות.סוכן AI ל-WhatsApp ב-n8n, והתשובה נכתבת בזרימת העבודה שלכםהפעילו סוכן AI ל-WhatsApp ב-n8n: POST חתום מביא את ההודעה והשיחה, והתשובה חוזרת תוך 20 שניות.תנו לסוכן ה-AI שלכם זיכרון: שישה חודשי צ'אטים ואנשי קשר ב-WhatsAppטענו עד 180 יום של צ'אטים ורשימת אנשי הקשר לזיכרון סוכן ה-AI בחיבור Coexistence: כלל 24 השעות, מקטעים, התקדמות ואחסון.וובהוקים של WhatsApp: ניתוב הודעות ישירות לשרת שלכםאיך וובהוקים של WhatsApp עובדים, מה Meta שולחת ואיך לנתב הודעות נכנסות ישירות לנקודת הקצה שלכם.אימות נקודת הקצה של וובהוק (Webhook) ב-WhatsAppMeta שולחת בקשת GET לנקודת הקצה לפני מסירת אירועים. מה נשלח, מה מחזירים ולמה תשובה שגויה נכשלת בשקט.AI ואדם על אותו מספר WhatsApp: ה-AI נסוג כשעונים מהטלפוןהפעילו AI ומענה ללקוחות בעצמכם על מספר WhatsApp Business אחד. תשובה מהטלפון משהה אוטומציות בצ'אט, 4 שעות כברירת מחדל.

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

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

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

נבדק ב-