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.
Pokušaji po prosljeđenoj isporuci, razmaknuti 1 min, 5 min, 30 min, 2 h, 6 h i 24 h, ukupno oko 33 sata.
Koliko dugo svaki pokušaj prosljeđivanja čeka 2xx prije nego se smatra neuspjelim.
Preporučeno ograničenje starosti parametra t u potpisu; ponovni pokušaji ponovno se potpisuju, pa ispravne isporuke ostaju unutar njega.
Koliko dugo Meta ponavlja izravni webhook koji je dobio bilo što osim HTTP 200, što može ponoviti poruke.
Najveći payload webhooka koji Meta šalje, uključujući dijelove povijesti.
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 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 |
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
{
"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.
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 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: 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.
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 razdobljeProvjereno na