Cum ajung mesajele WhatsApp la serverul dumneavoastră: direct sau gestionat și verificarea semnăturii
Fiecare număr conectat prin easyCoexistence are un singur mod de primire. Direct către sistemul dumneavoastră (direct): Meta trimite webhook-urile la endpoint-ul dumneavoastră HTTPS, un secret din URL este credențialul, iar automatizările sunt dezactivate. Prin easyCoexistence (gestionat): Meta livrează către easyCoexistence, automatizările pot răspunde, iar un Forward URL opțional primește valoarea originală trimisă de Meta, cu detaliile conexiunii, semnată cu X-EC-Signature, pentru verificare de către dumneavoastră.
Încercări pentru fiecare livrare redirecționată, la 1 min, 5 min, 30 min, 2 h, 6 h și 24 h distanță, adică circa 33 de ore în total.
Cât așteaptă fiecare încercare de redirecționare un răspuns 2xx înainte să fie considerată eșuată.
Limita recomandată pentru vârsta lui t din semnătură; reîncercările sunt semnate din nou, deci livrările autentice rămân în ea.
Cât timp reîncearcă Meta un webhook direct care a primit altceva decât HTTP 200, ceea ce poate repeta mesaje.
Cel mai mare payload de webhook trimis de Meta, inclusiv blocurile de istoric.
Jurnalele de rulare păstrate pentru un număr gestionat, cu textul mesajelor și al răspunsurilor; textul mesajelor în sine se păstrează 30, 90 sau 365 de zile, la alegerea dumneavoastră.
Care este diferența dintre direct și gestionat?
Unde livrează Meta webhook-urile de mesaje ale numărului. Gestionat, afișat ca Prin easyCoexistence, înseamnă că Meta livrează către easyCoexistence, care verifică semnătura Meta, rulează automatizările, păstrează conversațiile pentru Conversations și, dacă ați setat un Forward URL, trimite mai departe fiecare modificare Meta către dumneavoastră, semnată cu un secret pe care îl deține doar dumneavoastră. Direct, afișat ca Direct către sistemul dumneavoastră, înseamnă că easyCoexistence setează endpoint-ul dumneavoastră HTTPS ca webhook override pe contul WhatsApp Business al numărului, astfel încât Meta trimite direct către dumneavoastră, iar mesajele nu ajung niciodată la easyCoexistence.
Webhook-urile operaționale din spatele monitorizării, precum account_update și schimbările de calitate, rămân la easyCoexistence în ambele moduri, de aceea alertele continuă să funcționeze oricum.
| 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 |
Cum schimbați un număr între cele două moduri?
Pe pagina numărului, cardul Unde ajung mesajele primite arată modul ca două opțiuni, Prin easyCoexistence și Direct către sistemul dumneavoastră. Salvarea unei destinații de webhook, din cardul Direcționați mesajele primite către propriul webhook sau cu set_webhook_destination, face numărul direct. Alegerea opțiunii Prin easyCoexistence elimină imediat această destinație la Meta, deci adăugați aceeași adresă ca Forward URL pentru a continua să primiți. Redirecționările din coadă sunt eliminate când un număr părăsește modul gestionat, iar numerele conectate fără URL de webhook pornesc gestionate.
Din asistentul dumneavoastră AI, set_inbound_mode schimbă modul și setează redirecționarea dintr-un singur apel și returnează secretul de redirecționare o singură dată:
// 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
}Ce conține un POST redirecționat?
O modificare Meta per cerere, învelită, în loc de structura Meta cu object, entry și changes. id este identificatorul livrării, repetat în X-EC-Delivery și stabil între reîncercări. event este numele câmpului Meta, messages, smb_message_echoes, history sau smb_app_state_sync, repetat în X-EC-Event. received_at este momentul în care easyCoexistence a primit modificarea de la Meta, connection identifică numărul, iar value este exact ce a trimis Meta, astfel încât codul de parsare scris pentru payload-ul Meta funcționează și pe acesta. Statusurile livrărilor sosesc în interiorul evenimentelor messages, sub 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?" }
}]
}
}Cum verificați X-EC-Signature în Node.js?
Citiți antetul ca t=<secunde unix>,v1=<64 de caractere hexazecimale>. Respingeți un t aflat la mai mult de 5 minute față de ceasul dumneavoastră, calculați HMAC-SHA256 peste t, un punct și corpul brut, cu cheia formată din întregul secret de redirecționare ca text UTF-8, și comparați rezultatul cu v1 în timp constant. Abia apoi parsați JSON-ul. Răspundeți cu 2xx în 10 secunde și faceți munca după aceea, iar rețineți identificatorii livrărilor acceptate, ca o reîncercare să nu fie procesată de două ori.
// 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);Cum verificați în Python?
Aceleași patru verificări, cu biblioteca standard: un model strict pentru antet, vârsta lui t, hmac.new peste t, un punct și octeții bruti, și hmac.compare_digest. În FastAPI, corpul brut vine din await request.body(), iar BackgroundTasks rulează munca după ce s-a trimis 200. În Flask, folosiți request.get_data() și nu reconstruiți niciodată corpul cu json.dumps, pentru că separatorii impliciți ai Python adaugă spații, iar semnătura nu mai corespunde.
# 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)Cum sunt reîncercate livrările eșuate?
O redirecționare este considerată livrată când endpoint-ul dumneavoastră răspunde cu orice 2xx în 10 secunde. Orice altceva, un timeout, un 4xx, un 5xx sau o redirecționare HTTP, care nu este urmată, programează următoarea încercare la aproximativ 1 minut, 5 minute, 30 de minute, 2 ore, 6 ore și 24 de ore mai târziu, iar după a șaptea încercare livrarea este abandonată. Fiecare încercare este semnată din nou, cu un t nou, iar URL-ul trebuie să fie HTTPS public, verificat la salvare și din nou înainte de fiecare trimitere. Livrările pleacă de la cea mai veche, dar o livrare reîncercată poate ajunge după cele mai noi, deci sortați după marcajele de timp Meta.
Pe o destinație directă, reîncercările le face Meta: orice altceva decât HTTP 200 este reîncercat cu frecvență descrescătoare timp de până la 7 zile, iar aceste reîncercări pot repeta un mesaj. Deduplicați după identificatorul de mesaj Meta în ambele moduri, deoarece o modificare pe care Meta o retrimite este redirecționată din nou sub un identificator nou de livrare.
Cum știe un endpoint direct că un POST este autentic?
Nu din X-Hub-Signature-256. Meta semnează cu secretul aplicației care deține abonamentul, care pentru un număr conectat aici este al easyCoexistence și nu este distribuit, deci verificarea acelui antet cu secretul propriei aplicații Meta respinge livrările autentice. Token-ul de verificare dovedește endpoint-ul o singură dată, în timpul handshake-ului GET al Meta. Ce funcționează în schimb:
- Puneți 32 sau mai multe caractere aleatorii în calea URL-ului de callback și respingeți cererile fără ele; pentru rotație, salvați un URL nou.
- Folosiți un receptor generic, precum nodul Webhook din n8n, nu un trigger WhatsApp care așteaptă propria dumneavoastră aplicație Meta.
- Descărcați media după identificator de la Meta, cu token-ul numărului, astfel încât un identificator fals să eșueze.
- Pe servere self-hosted, puteți permite opțional doar rețeaua Meta, adică rutele anunțate de AS32934.
- Sau treceți la gestionat cu un Forward URL, unde X-EC-Signature dovedește fiecare POST.
Greșeli frecvente
- Trimiterea către Forward URL, fără modificări, a codului scris pentru structura Meta. O redirecționare conține o singură modificare: citiți event și value, nu object, entry și changes.
- Așteptarea unui X-EC-Event de statuses. Statusurile livrărilor vin în interiorul evenimentelor messages, în value.statuses, iar răspunsurile scrise în aplicație sosesc ca smb_message_echoes.
- Munca făcută înainte de răspuns. O redirecționare așteaptă 10 secunde, apoi aceeași livrare revine cu un t nou; răspundeți mai întâi cu 2xx și procesați dintr-o coadă.
- Trecerea la gestionat presupunând că vechiul URL mai primește. Destinația directă este eliminată chiar în acel moment; transmiteți forward_url în același apel set_inbound_mode.
easyCoexistence conectează un număr din aplicația WhatsApp Business la Cloud API prin Coexistence și vă permite să alegeți, pentru fiecare număr, unde ajung mesajele: direct de la Meta la server sau prin easyCoexistence, astfel încât automatizările să poată răspunde, iar o copie semnată ajunge la Forward URL. Monitorizarea și alertele funcționează în ambele moduri. De la US$ 9 până la US$ 0,75 pe număr pe lună, scăzând pe măsură ce adăugați numere, cu primele 3 zile gratuite.
Întrebări frecvente
Vede serverul dumneavoastră ce a răspuns o automatizare?
Nu textul. Meta raportează trimiterile prin API ca statusuri (sent, delivered, read) în interiorul evenimentelor messages, cu identificatorul mesajului; textul propriu-zis se află în jurnalul de rulare al automatizării, păstrat 30 de zile în fila Runs, și în Conversations pentru perioada aleasă de dumneavoastră.
Cum rotiți secretul de redirecționare?
Apăsați Secret nou pe pagina numărului sau apelați set_inbound_mode cu rotate_secret setat la true. Noul secret este afișat o singură dată și semnează totul de atunci încolo, inclusiv reîncercările livrărilor mai vechi, deci actualizați imediat serverul.
Are nevoie un Forward URL de handshake-ul GET al Meta?
Nu. Doar o destinație directă este apelată de Meta și trebuie să returneze hub.challenge. Un Forward URL este apelat de easyCoexistence și primește doar POST-uri semnate.
Poate un număr să aibă simultan o destinație directă și un Forward URL?
Nu. Un Forward URL funcționează doar cât timp numărul este gestionat, iar salvarea unei destinații directe îl face direct. Forward URL-ul și secretul lui sunt păstrate, deci revenirea la gestionat reia redirecționarea.
Continuați să citiți
Gata să începeți?
Configurați WhatsApp Coexistence în câteva minute, nu luni. Aplicația continuă să funcționeze pe telefon.
Începeți perioada de probă gratuităVerificat la