Prijavite seZapočnite besplatni probni period
Meta Tech Provider

Kako WhatsApp poruke stižu do vašeg servera: direktno ili upravljano, i provera potpisa

Svaki broj povezan preko easyCoexistence ima jedan režim dolaznih poruka. Pravo na vaš sistem (direktno): Meta šalje svoje webhookove na vaš HTTPS endpoint, tajna u URL-u je kredencijal, a automatizacije su isključene. Preko easyCoexistence (upravljano): Meta isporučuje easyCoexistence-u, automatizacije mogu da odgovaraju, a opcioni Forward URL dobija Metinu originalnu vrednost sa podacima o vezi, potpisanu sa X-EC-Signature za proveru.

7 attempts

Pokušaja po prosleđenoj isporuci, razmaknutih 1 min, 5 min, 30 min, 2 h, 6 h i 24 h, ukupno oko 33 sata.

10 s

Koliko dugo svaki pokušaj prosleđivanja čeka 2xx pre nego što se računa kao neuspeh.

5 min

Preporučeno ograničenje starosti t iz potpisa; ponovni pokušaji se ponovo potpisuju, pa ispravne isporuke ostaju unutar njega.

7 days

Koliko dugo Meta ponavlja direktni webhook koji je dobio bilo šta osim HTTP 200, što može ponoviti poruke.

3 MB

Najveći webhook payload koji Meta šalje, uključujući delove istorije.

30 days

Dnevnici izvršavanja za upravljani broj, sa tekstom poruka i odgovora; sam tekst poruka čuva se 30, 90 ili 365 dana, po vašem izboru.

Koja je razlika između direktnog i upravljanog režima?

Gde Meta isporučuje webhookove za poruke broja. Upravljani režim, prikazan kao „Preko easyCoexistence“, znači da Meta isporučuje easyCoexistence-u, koji proverava Metin potpis, pokreće vaše automatizacije, čuva razgovore za Conversations i, ako postavite Forward URL, prosleđuje svaku Metinu promenu vama, potpisanu tajnom koju samo vi imate. Direktni režim, prikazan kao „Pravo na vaš sistem“, znači da easyCoexistence postavlja vaš HTTPS endpoint kao webhook override na WhatsApp Business nalogu broja, pa Meta šalje direktno vama i poruke nikada ne stižu do easyCoexistence-a.

Operativni webhookovi za praćenje, kao što su account_update i promene kvaliteta, ostaju kod easyCoexistence-a u oba režima, zato upozorenja rade u svakom slučaju.

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

Kako prebaciti broj sa jednog režima na drugi?

Na stranici broja, kartica „Gde idu dolazne poruke“ prikazuje režim kao dva izbora, „Preko easyCoexistence“ i „Pravo na vaš sistem“. Čuvanje odredišta webhooka, u kartici „Usmeri dolazne poruke na sopstveni webhook“ ili preko set_webhook_destination, čini broj direktnim. Izbor opcije „Preko easyCoexistence“ odmah uklanja to odredište kod Mete, pa dodajte isti URL kao Forward URL da biste nastavili da primate. Isporuke koje čekaju u redu za prosleđivanje se odbacuju kada broj napusti upravljani režim, a brojevi povezani bez webhook URL-a počinju kao upravljani.

Iz vašeg AI asistenta, set_inbound_mode menja režim i postavlja prosleđivanje jednim pozivom, i vraća tajni ključ za prosleđivanje samo jednom:

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
}

Šta sadrži prosleđeni POST?

Jednu Metinu promenu po zahtevu, umotanu, umesto Metinog omotača object, entry i changes. id je ID isporuke, ponovljen u X-EC-Delivery i stabilan kroz ponovne pokušaje. event je naziv Metinog polja: messages, smb_message_echoes, history ili smb_app_state_sync, ponovljen u X-EC-Event. received_at je trenutak kada je easyCoexistence primio promenu od Mete, connection označava broj, a value je tačno ono što je Meta poslala, pa kod za parsiranje napisan za Metin payload radi i na njemu. Statusi isporuke stižu unutar događaja messages, pod 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?" }
    }]
  }
}

Kako proveriti X-EC-Signature u Node.js?

Pročitajte zaglavlje kao t=<unix sekunde>,v1=<64 heksadecimalna znaka>. Odbacite t koji se od vašeg sata razlikuje za više od 5 minuta, izračunajte HMAC-SHA256 nad t, tačkom i sirovim telom, ključem koji je cela forward tajna kao UTF-8 tekst, i uporedite rezultat sa v1 u konstantnom vremenu. Tek tada parsirajte JSON. Odgovorite sa 2xx u roku od 10 sekundi, a posao obavite posle, i zapamtite ID-jeve isporuka koje ste prihvatili da se ponovni pokušaj ne obradi dvaput.

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

Kako to proveriti u Pythonu?

Isti četiri koraka sa standardnom bibliotekom: strogi obrazac za zaglavlje, starost t, hmac.new nad t, tačkom i sirovim bajtovima, i hmac.compare_digest. U FastAPI sirovo telo dolazi iz await request.body(), a BackgroundTasks pokreće posao nakon što se 200 pošalje. U Flasku koristite request.get_data(), i nikada ne rekonstruišite telo sa json.dumps, jer podrazumevani separatori Pythonovi dodaju razmake i potpis se više ne poklapa.

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)

Kako se neuspele isporuke ponovo pokušavaju?

Prosleđivanje se računa kao isporučeno kada vaš endpoint odgovori bilo kojim 2xx u roku od 10 sekundi. Sve ostalo, istek vremena, 4xx, 5xx ili preusmeravanje, koje se ne prati, zakazuje sledeći pokušaj oko 1 min, 5 min, 30 min, 2 h, 6 h i 24 h kasnije, a posle sedmog pokušaja isporuka se napušta. Svaki pokušaj se ponovo potpisuje svežim t, a URL mora biti javni HTTPS, što se proverava pri čuvanju i pre svakog slanja. Isporuke idu od najstarije ka najnovijoj, ali ponovljena može stići posle novijih, pa sortirajte prema Metinim vremenskim oznakama.

Na direktnom odredištu ponovne pokušaje vodi Meta: sve osim HTTP 200 ponavlja se sa sve manjom učestalošću do 7 dana, a ti pokušaji mogu ponoviti poruku. U oba režima uklonite duplikate po Metinom ID-u poruke, jer promena koju Meta ponovo isporuči biće prosleđena ponovo pod novim ID-jem isporuke.

Kako direktni endpoint zna da je POST autentičan?

Ne po X-Hub-Signature-256. Meta potpisuje app secret aplikacije koja poseduje pretplatu, a za broj povezan ovde to je aplikacija easyCoexistence, i ta tajna nije deljena. Zato provera tog zaglavlja sopstvenom app secret tajnom odbacuje autentične isporuke. Verify token dokazuje endpoint samo jednom, tokom Metinog GET rukovanja. Umesto toga, radi sledeće:

  • Stavite 32 ili više nasumičnih znakova u putanju callback URL-a i odbacite zahteve bez njih; za rotaciju sačuvajte novi URL.
  • Koristite generički prijemnik, kao što je n8n Webhook čvor, a ne WhatsApp okidač koji očekuje vašu sopstvenu Meta aplikaciju.
  • Preuzmite medijski sadržaj po ID-ju od Mete tokenom broja, pa lažni ID jednostavno ne prolazi.
  • Na sopstvenim serverima možete po želji dozvoliti samo Metinu mrežu, rute koje oglašava AS32934.
  • Ili pređite na upravljani režim sa Forward URL, gde X-EC-Signature dokazuje svaki POST.

Česte greške

  • Usmeravanje koda napisanog za Metin omotač na Forward URL bez izmene. Prosleđivanje nosi jednu promenu: čitajte event i value, a ne object, entry i changes.
  • Čekanje na X-EC-Event sa vrednošću statuses. Statusi isporuke dolaze unutar događaja messages, u value.statuses, a odgovori ukucani u aplikaciji stižu kao smb_message_echoes.
  • Obrada pre odgovora. Prosleđivanje čeka 10 sekundi, pa ista isporuka stiže ponovo sa novim t; prvo odgovorite sa 2xx, a obradu pokrenite iz reda.
  • Prelazak na upravljani režim uz pretpostavku da stari URL i dalje prima. Direktno odredište se uklanja tog trenutka; prosledite forward_url u istom pozivu set_inbound_mode.
Ovo radite uz EasyCoexistence

easyCoexistence povezuje broj WhatsApp Business aplikacije sa Metinim Cloud API-jem preko Coexistence i omogućava vam da za svaki broj izaberete kuda idu poruke: direktno od Mete do vašeg servera, ili preko easyCoexistence-a, tako da automatizacije mogu da odgovaraju, a potpisana kopija stiže na vaš Forward URL. Praćenje i upozorenja rade u oba režima. Od US$ 9 do US$ 0.75 po broju mesečno, što pada kako dodajete brojeve, prva 3 dana besplatno.

Često postavljana pitanja

Da li će moj server videti šta je automatizacija odgovorila?

Ne tekst. Meta prijavljuje slanja preko API-ja kao statuse (poslato, isporučeno, pročitano) unutar događaja messages, sa ID-jem poruke; sam tekst je u dnevniku izvršavanja automatizacije, koji se čuva 30 dana na kartici „Izvršavanja“, i u Conversations onoliko dugo koliko ste izabrali.

Kako da rotiram tajni ključ za prosleđivanje?

Kliknite „Nova tajna“ na stranici broja ili pozovite set_inbound_mode sa rotate_secret postavljenim na true. Nova tajna se prikazuje samo jednom i od tada potpisuje sve, uključujući ponovne pokušaje starijih isporuka, pa odmah ažurirajte server.

Da li Forward URL zahteva Metino GET rukovanje?

Ne. Metu poziva samo direktno odredište i mora da vrati hub.challenge. Forward URL poziva easyCoexistence i prima samo potpisane POST zahteve.

Može li broj imati direktno odredište i Forward URL istovremeno?

Ne. Forward URL radi samo dok je broj upravljan, a čuvanje direktnog odredišta ga čini direktnim. Forward URL i njegova tajna se čuvaju, pa se povratkom na upravljani režim prosleđivanje nastavlja.

Nastavite sa čitanjem

Spremni da počnete?

Podesite WhatsApp Coexistence za nekoliko minuta, a ne meseci. Aplikacija nastavlja da radi na telefonu.

Započnite besplatni probni period

Provereno na