Prijavite seZapočnite besplatno probno razdoblje
Meta Tech Provider

Kako WhatsApp poruke stižu na vaš poslužitelj: izravno ili upravljano, i provjera potpisa

Svaki broj povezan preko easyCoexistence ima jedan način dolaznih poruka. Izravno na vaš sustav (izravno): Meta šalje webhookove na vaš HTTPS endpoint, tajna u URL-u je vjerodajnica, a automatizacije su isključene. Preko easyCoexistence (upravljano): Meta šalje u easyCoexistence, automatizacije mogu odgovarati, a neobavezni Forward URL dobiva Metinu izvornu vrijednost s podacima o vezi, potpisanu s X-EC-Signature za vašu provjeru.

7 attempts

Pokušaji po prosljeđenoj isporuci, razmaknuti 1 min, 5 min, 30 min, 2 h, 6 h i 24 h, ukupno oko 33 sata.

10 s

Koliko dugo svaki pokušaj prosljeđivanja čeka 2xx prije nego se smatra neuspjelim.

5 min

Preporučeno ograničenje starosti parametra t u potpisu; ponovni pokušaji ponovno se potpisuju, pa ispravne isporuke ostaju unutar njega.

7 days

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

3 MB

Najveći payload webhooka koji Meta šalje, uključujući dijelove povijesti.

30 days

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

Koja je razlika između izravnog i upravljanog načina?

Gdje Meta isporučuje webhookove poruka za broj. Upravljano, prikazano kao „Through easyCoexistence“, znači da Meta šalje u easyCoexistence, koji provjerava Metin potpis, pokreće vaše automatizacije, sprema razgovore za odjeljak Razgovori i, ako postavite Forward URL, prosljeđuje svaku Metinu promjenu vama, potpisanu tajnom koju samo vi imate. Izravno, prikazano kao „Straight to your system“, znači da easyCoexistence postavlja vaš HTTPS endpoint kao webhook override za WhatsApp Business Account tog broja, pa Meta šalje izravno vama i poruke nikada ne dolaze u easyCoexistence.

Operativni webhookovi koji stoje iza praćenja, poput account_update i promjena kvalitete, ostaju u easyCoexistence u oba načina, zbog čega upozorenja rade bez obzira na način.

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 između ova dva načina?

Na stranici broja kartica Where incoming messages go prikazuje način kao dva izbora, „Through easyCoexistence“ i „Straight to your system“. Spremanje odredišta webhooka, u kartici „Route incoming messages to your own webhook“ ili s set_webhook_destination, postavlja broj na izravni način. Odabir opcije „Through easyCoexistence“ odmah uklanja to odredište kod Mete, pa dodajte isti URL kao Forward URL da biste i dalje primali poruke. Prosljeđivanja u redu čekanja odbacuju se kada broj napusti upravljani način, a brojevi povezani bez webhook URL-a automatski počinju kao upravljani.

Iz vašeg AI alata, set_inbound_mode mijenja način i postavlja prosljeđivanje jednim pozivom, a tajnu za prosljeđivanje vraća 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
}

Što sadrži prosljeđeni POST?

Jednu Metinu promjenu po zahtjevu, umotanu, a ne Metin omotač 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 promjenu od Mete, connection označava broj, a value je točno ono što je Meta poslala, pa kod za parsiranje Metinog payloada radi i na ovome. Statusi isporuke dolaze unutar messages događaja, 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 provjeriti X-EC-Signature u Node.js?

Zaglavlje pročitajte 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, točkom i sirovim tijelom zahtjeva, s cijelom tajnom za prosljeđivanje kao ključem u UTF-8 tekstu, i usporedite rezultat s v1 u konstantnom vremenu. Tek tada parsirajte JSON. Odgovorite 2xx unutar 10 sekundi, a posao obavite nakon toga, i zapamtite ID-jeve isporuka koje ste prihvatili kako ponovni pokušaj ne bi bio obrađen 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 provjeriti u Pythonu?

Ista četiri koraka sa standardnom bibliotekom: stroga provjera oblika zaglavlja, starost t, hmac.new nad t, točkom i sirovim bajtovima, i hmac.compare_digest. U FastAPI sirovo tijelo dolazi iz await request.body(), a BackgroundTasks izvršava posao nakon što je 200 poslan. U Flasku koristite request.get_data() i nikada ne rekonstruirajte tijelo s json.dumps, jer zadani separatori u Pythonu dodaju razmake i potpis više ne odgovara.

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 neuspjele isporuke ponovno pokušavaju?

Prosljeđivanje se smatra isporučenim kad vaš endpoint odgovori bilo kojim 2xx unutar 10 sekundi. Sve ostalo, timeout, 4xx, 5xx ili preusmjeravanje koje se ne slijedi, zakazuje sljedeći pokušaj otprilike 1 minutu, 5 minuta, 30 minuta, 2 sata, 6 sati i 24 sata kasnije, a nakon sedmog pokušaja isporuka se odbacuje. Svaki pokušaj ponovno se potpisuje novim t, a URL mora biti javni HTTPS, provjeren pri spremanju i ponovno prije svakog slanja. Isporuke odlaze od najstarije, ali ponovno poslana može stići nakon novijih, pa razvrstajte prema Metinim vremenskim oznakama.

Na izravnom odredištu ponovne pokušaje radi Meta: sve osim HTTP 200 ponavlja se s opadajućom učestalošću do 7 dana, a ti ponovni pokušaji mogu ponoviti poruku. Deduplicirajte prema Metinom ID-u poruke u oba načina, jer promjenu koju Meta ponovno isporuči easyCoexistence prosljeđuje ponovno pod novim ID-jem isporuke.

Kako izravni endpoint zna da je POST autentičan?

Ne po X-Hub-Signature-256. Meta potpisuje tajnom aplikacije koja posjeduje pretplatu. Za broj povezan ovdje to je aplikacija easyCoexistence, a njezina tajna nije dijeljena, pa provjera tog zaglavlja vašom tajnom Meta aplikacije odbacuje autentične isporuke. Verify token dokazuje endpoint samo jednom, tijekom Metina GET rukovanja. Umjesto toga funkcionira sljedeće:

  • Stavite 32 ili više nasumičnih znakova u putanju callback URL-a i odbacite zahtjeve bez njih; za zamjenu spremite novi URL.
  • Koristite generički primatelj, poput n8n Webhook čvora, a ne WhatsApp okidač koji očekuje vašu vlastitu Meta aplikaciju.
  • Preuzimajte medije po ID-u iz Mete s tokenom broja, pa lažni ID jednostavno ne uspije.
  • Na samostalno hostiranim poslužiteljima po želji dopustite samo Metinu mrežu, odnosno rute koje oglašava AS32934.
  • Ili prijeđite na upravljano s Forward URL-om, gdje X-EC-Signature dokazuje svaki POST.

Uobičajene pogreške

  • Usmjeravanje koda pisanog za Metin omotač izravno na Forward URL bez promjena. Prosljeđivanje nosi jednu promjenu: čitajte event i value, a ne object, entry i changes.
  • Čekanje X-EC-Event vrijednosti statuses. Statusi isporuke dolaze unutar messages događaja, u value.statuses, a odgovori upisani u aplikaciji stižu kao smb_message_echoes.
  • Obrada prije odgovora. Prosljeđivanje čeka 10 sekundi, zatim se ista isporuka vraća s novim t; prvo odgovorite 2xx, a obradu radite iz reda čekanja.
  • Prijelaz na upravljano uz pretpostavku da stari URL i dalje prima. Izravno odredište se u tom trenutku uklanja; proslijedite forward_url u istom pozivu set_inbound_mode.
Radite ovo uz EasyCoexistence

easyCoexistence povezuje WhatsApp Business aplikaciju broja s Metinim Cloud API-jem putem značajke Coexistence i omogućuje vam da za svaki broj odaberete kamo idu poruke: izravno od Mete na vaš poslužitelj ili preko easyCoexistence, pa automatizacije mogu odgovarati, a potpisana kopija stiže na vaš Forward URL. Praćenje i upozorenja rade u oba načina. Od US$ 9 do US$ 0.75 po broju mjesečno, cijena pada kako dodajete brojeve, uz prva 3 dana besplatno.

Često postavljana pitanja

Hoće li moj poslužitelj vidjeti što je automatizacija odgovorila?

Ne sam tekst. Meta prijavljuje slanja iz API-ja kao statuse (sent, delivered, read) unutar messages događaja, s ID-jem poruke. Sam tekst nalazi se u zapisu izvršavanja automatizacije, koji se čuva 30 dana na kartici Runs, i u Razgovorima onoliko dugo koliko ste odabrali.

Kako zamijeniti tajnu za prosljeđivanje?

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

Treba li Forward URL Metino GET rukovanje?

Ne. Meta poziva samo izravno odredište i mora vratiti hub.challenge. Forward URL poziva easyCoexistence i prima samo potpisane POST zahtjeve.

Može li broj imati izravno odredište i Forward URL istodobno?

Ne. Forward URL radi samo dok je broj upravljan, a spremanje izravnog odredišta čini ga izravnim. Forward URL i njegova tajna se čuvaju, pa prelazak natrag na upravljano nastavlja prosljeđivanje.

Nastavite čitati

Spremni za početak?

Postavite WhatsApp Coexistence u nekoliko minuta, a ne mjeseci. Aplikacija i dalje radi na telefonu.

Započnite besplatno probno razdoblje

Provjereno na