Mag-log inMagsimula ng Libreng Trial
Meta Tech Provider

Paano dumarating ang mga mensahe ng WhatsApp sa inyong server: direct o managed, at pag-verify ng signature

Bawat numerong naka-connect sa pamamagitan ng easyCoexistence ay may isang inbound mode. Straight to your system (direct): ipinapadala ng Meta ang mga webhook nito sa inyong HTTPS endpoint, ang secret sa URL ang credential, at naka-off ang automations. Through easyCoexistence (managed): ipinapadala ng Meta ang mga webhook sa easyCoexistence, maaaring sumagot ang automations, at ang opsyonal na Forward URL ay tumatanggap ng orihinal na value ng Meta kasama ang mga detalye ng koneksyon, naka-sign gamit ang X-EC-Signature para i-verify ninyo.

7 attempts

Mga pagsubok bawat forwarded delivery, may pagitan na 1 min, 5 min, 30 min, 2 h, 6 h at 24 h, humigit-kumulang 33 oras sa kabuuan.

10 s

Gaano katagal maghihintay ang bawat pagsubok ng forward para sa 2xx bago ituring na nabigo.

5 min

Iminumungkahing limitasyon sa edad ng t ng signature; muling pinipirmahan ang mga retry, kaya nananatili sa loob nito ang tunay na delivery.

7 days

Gaano katagal inuulit ng Meta ang direct webhook na anumang sagot maliban sa HTTP 200, na maaaring magdulot ng paulit-ulit na mensahe.

3 MB

Pinakamalaking webhook payload na ipinapadala ng Meta, kasama ang history chunks.

30 days

Mga run log na itinatago para sa managed na numero, kasama ang teksto ng mensahe at sagot; ang mismong teksto ng mensahe ay itinatago nang 30, 90 o 365 araw, ayon sa pipiliin ninyo.

Ano ang pagkakaiba ng direct at managed?

Kung saan ipinapadala ng Meta ang mga webhook ng mensahe ng numero. Managed, ipinapakita bilang Through easyCoexistence, ibig sabihin ipinapadala ng Meta sa easyCoexistence, na sinusuri ang signature ng Meta, pinapatakbo ang inyong automations, itinatago ang mga chat para sa Conversations at, kung may itinakdang Forward URL, ipinapasa ang bawat Meta change sa inyo, naka-sign gamit ang secret na kayo lamang ang may hawak. Direct, ipinapakita bilang Straight to your system, ibig sabihin itinatakda ng easyCoexistence ang inyong HTTPS endpoint bilang webhook override sa WhatsApp Business Account ng numero, kaya diretsong nagpo-post ang Meta sa inyo at hindi kailanman dumadaan sa easyCoexistence ang mga mensahe.

Ang mga operational webhook na nasa likod ng pagmo-monitor, gaya ng account_update at quality changes, ay nananatili sa easyCoexistence sa parehong mode, kaya patuloy na gumagana ang alerts anuman ang piliin.

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

Paano ililipat ang numero sa pagitan ng dalawa?

Sa pahina ng numero, ipinapakita ng card na Where incoming messages go ang mode bilang dalawang pagpipilian, ang Through easyCoexistence at ang Straight to your system. Ang pag-save ng webhook destination sa card na Ipadala ang papasok na mensahe sa sarili ninyong webhook, o gamit ang set_webhook_destination, ay ginagawang direct ang numero. Ang pagpili sa Through easyCoexistence ay agad na inaalis ang destination na iyon sa Meta, kaya idagdag ang parehong URL bilang Forward URL para patuloy na makatanggap. Ang nakapilang forward ay natatanggal kapag lumabas ang numero sa managed mode, at ang mga numerong naka-connect nang walang webhook URL ay nagsisimula sa managed.

Mula sa inyong AI, inililipat ng set_inbound_mode ang mode at itinatakda ang forward sa iisang tawag, at ibinabalik ang forward secret nang isang beses:

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
}

Ano ang laman ng forwarded na POST?

Isang change ng Meta bawat request, nakabalot, sa halip na envelope ng Meta na object, entry at changes. Ang id ay delivery id, inuulit sa X-EC-Delivery at nananatiling pareho sa bawat retry. Ang event ay pangalan ng field ng Meta: messages, smb_message_echoes, history o smb_app_state_sync, inuulit sa X-EC-Event. Ang received_at ay kung kailan nakuha ng easyCoexistence ang change mula sa Meta, ang connection ay tumutukoy sa numero, at ang value ay eksaktong ipinadala ng Meta, kaya gumagana rin dito ang parsing code na isinulat para sa payload ng Meta. Ang mga status ng delivery ay nasa loob ng messages events, sa ilalim ng 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?" }
    }]
  }
}

Paano i-verify ang X-EC-Signature sa Node.js?

Basahin ang header bilang t=<unix seconds>,v1=<64 hex characters>. Tanggihan ang t na lalampas nang 5 minuto sa inyong orasan, kuwentahin ang HMAC-SHA256 sa t, isang tuldok, at ang raw body, gamit ang buong forward secret bilang UTF-8 text na susi, at ihambing ang resulta sa v1 sa constant time. Saka lamang i-parse ang JSON. Sumagot ng 2xx sa loob ng 10 segundo at gawin ang trabaho pagkatapos, at tandaan ang mga delivery id na tinanggap ninyo para hindi maproseso nang dalawang beses ang retry.

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);

Paano ito i-verify sa Python?

Ang parehong apat na check gamit ang standard library: mahigpit na pattern para sa header, edad ng t, hmac.new sa t, tuldok, at raw bytes, at hmac.compare_digest. Sa FastAPI, nagmumula ang raw body sa await request.body(), at pinapatakbo ng BackgroundTasks ang trabaho pagkatapos maipadala ang 200. Sa Flask, gamitin ang request.get_data(), at huwag na huwag buuin muli ang body gamit ang json.dumps, dahil nagdadagdag ng espasyo ang default separators ng Python kaya hindi na tugma ang signature.

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)

Paano inuulit ang mga bigong delivery?

Itinuturing na delivered ang forward kapag sumagot ang inyong endpoint ng anumang 2xx sa loob ng 10 segundo. Ang anumang iba pa, timeout, 4xx, 5xx o redirect na hindi sinusundan, ay nag-iiskedyul ng susunod na pagsubok nang humigit-kumulang 1 minuto, 5 minuto, 30 minuto, 2 oras, 6 na oras at 24 na oras pagkatapos, at pagkatapos ng ikapitong pagsubok ay ina-abandon ang delivery. Muling pinipirmahan ang bawat pagsubok ng bagong t, at kailangang public HTTPS ang URL, na sinusuri sa pag-save at muli bago ang bawat pagpapadala. Ipinapadala ang mga delivery mula sa pinakaluma, ngunit ang na-retry ay maaaring dumating pagkatapos ng mas bagong delivery, kaya i-order ayon sa timestamps ng Meta.

Sa direct destination, ang Meta ang nagre-retry: ang anumang hindi HTTP 200 ay inuulit nang papabagal ang dalas hanggang 7 araw, at maaaring maulit ang mensahe dahil dito. I-deduplicate sa ID ng mensahe ng Meta sa parehong mode, dahil ang change na muling ipinadala ng Meta ay ipino-forward muli sa ilalim ng bagong delivery id.

Paano nalalaman ng direct endpoint na tunay ang POST?

Hindi mula sa X-Hub-Signature-256. Pinipirmahan ng Meta gamit ang app secret ng app na may-ari ng subscription, na para sa numerong naka-connect dito ay sa easyCoexistence at hindi ibinabahagi, kaya ang pag-check ng header na iyon gamit ang sarili ninyong Meta app secret ay tinatanggihan ang tunay na delivery. Ang verify token ay nagpapatunay lamang ng endpoint nang isang beses, sa GET handshake ng Meta. Ang gumagana sa halip:

  • Maglagay ng 32 o higit pang random na karakter sa path ng callback URL at tanggihan ang mga request na wala nito; para mag-rotate, mag-save ng bagong URL.
  • Gumamit ng generic receiver, gaya ng n8n Webhook node, hindi WhatsApp trigger na nangangailangan ng sarili ninyong Meta app.
  • I-download ang media sa pamamagitan ng id mula sa Meta gamit ang token ng numero, kaya kapag peke ang id, basta na lamang itong mabibigo.
  • Sa self-hosted na server, opsyonal na payagan lamang ang network ng Meta, ang mga route na ina-anunsyo ng AS32934.
  • O lumipat sa managed na may Forward URL, kung saan pinatutunayan ng X-EC-Signature ang bawat POST.

Mga karaniwang pagkakamali

  • Ang paggamit ng code na isinulat para sa envelope ng Meta sa Forward URL nang hindi binabago. Ang forward ay may iisang change: basahin ang event at value, hindi object, entry at changes.
  • Paghihintay ng X-EC-Event na statuses. Nasa loob ng messages events ang mga status ng delivery, sa value.statuses, at ang mga reply na tina-type sa app ay dumarating bilang smb_message_echoes.
  • Paggawa ng trabaho bago sumagot. Naghihintay ng 10 segundo ang forward, pagkatapos babalik ang parehong delivery na may bagong t; sumagot muna ng 2xx at iproseso mula sa queue.
  • Paglipat sa managed at pag-aakalang tatanggap pa rin ang lumang URL. Nabubura ang direct destination sa sandaling iyon; ipasa ang forward_url sa parehong tawag ng set_inbound_mode.
Ginagawa ito gamit ang EasyCoexistence

Ikinokonekta ng easyCoexistence ang numero ng WhatsApp Business app sa Cloud API ng Meta sa pamamagitan ng Coexistence, at hinahayaan kayong pumili, bawat numero, kung saan pupunta ang mga mensahe nito: diretso mula sa Meta papunta sa inyong server, o sa pamamagitan ng easyCoexistence para makasagot ang automations at makarating ang naka-sign na kopya sa inyong Forward URL. Gumagana ang pagmo-monitor at alerts sa parehong mode. Mula US$ 9 hanggang US$ 0.75 kada naka-connect na numero kada buwan, bumababa habang dumarami ang mga numero, at may unang 3 araw na free trial.

Mga madalas itanong

Makikita ba ng server ko ang isinagot ng automation?

Hindi ang teksto. Iniuulat ng Meta ang mga API send bilang status (sent, delivered, read) sa loob ng messages events, kasama ang ID ng mensahe; ang mismong teksto ay nasa run log ng automation, na itinatago nang 30 araw sa tab na Runs, at sa Conversations sa panahong pinili ninyo.

Paano ko i-rotate ang forward secret?

I-click ang New secret sa pahina ng numero, o tawagin ang set_inbound_mode na may rotate_secret na naka-set sa true. Ipapakita ang bagong secret nang isang beses at pipirmahan nito ang lahat mula ngayon, kasama ang mga retry ng mas lumang delivery, kaya i-update agad ang inyong server.

Kailangan ba ng Forward URL ang GET handshake ng Meta?

Hindi. Tanging direct destination lamang ang tinatawagan ng Meta at kailangang ibalik ang hub.challenge. Tinatawagan ng easyCoexistence ang Forward URL at tumatanggap lamang ng naka-sign na POST.

Maaari bang magkaroon ng direct destination at Forward URL nang sabay ang isang numero?

Hindi. Gumagana lamang ang Forward URL habang managed ang numero, at ang pag-save ng direct destination ay ginagawang direct ito. Nananatili ang Forward URL at ang secret nito, kaya kapag bumalik sa managed, ipagpapatuloy ang forwarding.

Magpatuloy sa pagbabasa

Handa na po ba kayong magsimula?

I-set up ang WhatsApp Coexistence sa loob ng ilang minuto, hindi buwan. Patuloy na gumagana ang app sa telepono.

Magsimula ng Libreng Trial

Na-verify noong