Jak wiadomości WhatsApp docierają na serwer: bezpośrednio czy zarządzane, oraz weryfikacja podpisu
Każdy numer połączony przez easyCoexistence ma jeden tryb odbioru wiadomości. Prosto do Twojego systemu (tryb bezpośredni): Meta wysyła swoje webhooki na Twój endpoint HTTPS, sekret w adresie URL jest poświadczeniem, a automatyzacje są wyłączone. Przez easyCoexistence (tryb zarządzany): Meta dostarcza do easyCoexistence, automatyzacje mogą odpowiadać, a opcjonalny Forward URL otrzymuje oryginalną wartość Meta wraz ze szczegółami połączenia, podpisaną nagłówkiem X-EC-Signature do weryfikacji po Twojej stronie.
Próby dla każdego przekazanego dostarczenia, w odstępach 1 min, 5 min, 30 min, 2 h, 6 h i 24 h, łącznie około 33 godzin.
Jak długo każda próba przekazania czeka na odpowiedź 2xx, zanim zostanie uznana za nieudaną.
Zalecany limit wieku t w podpisie; ponowienia są podpisywane ponownie, więc prawdziwe dostarczenia mieszczą się w nim.
Jak długo Meta ponawia bezpośredni webhook, który dostał coś innego niż HTTP 200, co może powtórzyć wiadomości.
Największy payload webhooka wysyłany przez Meta, łącznie z fragmentami historii.
Dzienniki uruchomień zachowywane dla numeru zarządzanego, z treścią wiadomości i odpowiedzi; sama treść wiadomości jest przechowywana 30, 90 lub 365 dni, do wyboru.
Jaka jest różnica między trybem bezpośrednim a zarządzanym?
Miejsce, w którym Meta dostarcza webhooki wiadomości numeru. Tryb zarządzany, widoczny jako Przez easyCoexistence, oznacza, że Meta dostarcza do easyCoexistence, które sprawdza podpis Meta, uruchamia Twoje automatyzacje, przechowuje czaty dla Conversations i, jeśli ustawisz Forward URL, przekazuje każdą zmianę Meta dalej, podpisaną sekretem znanym tylko Tobie. Tryb bezpośredni, widoczny jako Prosto do Twojego systemu, oznacza, że easyCoexistence ustawia Twój endpoint HTTPS jako nadpisanie webhooka na koncie WhatsApp Business numeru, więc Meta wysyła dane prosto do Ciebie, a wiadomości nigdy nie trafiają do easyCoexistence.
Webhooki operacyjne stojące za monitorowaniem, na przykład account_update i zmiany jakości, pozostają w easyCoexistence w obu trybach, dlatego powiadomienia działają zawsze.
| 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 |
Jak przełączyć numer między tymi trybami?
Na stronie numeru karta Gdzie trafiają przychodzące wiadomości pokazuje tryb jako dwa wybory: Przez easyCoexistence i Prosto do Twojego systemu. Zapisanie celu webhooka w karcie Kieruj przychodzące wiadomości na własny webhook albo przez set_webhook_destination ustawia numer jako bezpośredni. Wybranie opcji Przez easyCoexistence natychmiast usuwa ten cel u Meta, więc dodaj ten sam adres URL jako Forward URL, by dalej otrzymywać dane. Zaległe przekazania są usuwane, gdy numer opuszcza tryb zarządzany, a numery połączone bez adresu webhooka zaczynają w trybie zarządzanym.
Z poziomu Twojej AI set_inbound_mode przełącza tryb i ustawia przekazywanie jednym wywołaniem, a sekret przekazywania zwraca tylko raz:
// 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
}Co zawiera przekazany POST?
Jedną zmianę Meta na żądanie, opakowaną, zamiast koperty object, entry i changes Meta. id to identyfikator dostarczenia, powtórzony w X-EC-Delivery i stały przy ponowieniach. event to nazwa pola Meta: messages, smb_message_echoes, history lub smb_app_state_sync, powtórzona w X-EC-Event. received_at to moment, w którym easyCoexistence otrzymało zmianę od Meta, connection identyfikuje numer, a value to dokładnie to, co wysłała Meta, więc kod parsujący payload Meta działa także na nim. Statusy dostarczenia przychodzą wewnątrz zdarzeń messages, 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?" }
}]
}
}Jak zweryfikować X-EC-Signature w Node.js?
Odczytaj nagłówek jako t=<sekundy unixowe>,v1=<64 znaki szesnastkowe>. Odrzuć t oddalone od Twojego zegara o więcej niż 5 minut, oblicz HMAC-SHA256 po t, kropce i surowym ciele żądania, kluczem jest cały sekret przekazywania jako tekst UTF-8, i porównaj wynik z v1 w stałym czasie. Dopiero potem parsuj JSON. Odpowiedz 2xx w ciągu 10 sekund, a pracę wykonaj później, i zapamiętaj przyjęte identyfikatory dostarczeń, aby ponowienie nie zostało przetworzone dwa razy.
// 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);Jak zweryfikować to w Pythonie?
Te same cztery sprawdzenia ze standardową biblioteką: ścisły wzorzec nagłówka, wiek t, hmac.new po t, kropce i surowych bajtach oraz hmac.compare_digest. W FastAPI surowe ciało pobierasz przez await request.body(), a BackgroundTasks wykonuje pracę po wysłaniu 200. We Flasku użyj request.get_data() i nigdy nie odtwarzaj ciała przez json.dumps, bo domyślne separatory Pythona dodają spacje i podpis przestaje się zgadzać.
# 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)Jak ponawiane są nieudane dostarczenia?
Przekazanie uznaje się za dostarczone, gdy Twój endpoint odpowie dowolnym kodem 2xx w ciągu 10 sekund. Wszystko inne, czyli przekroczenie czasu, 4xx, 5xx lub przekierowanie, którego nie śledzimy, planuje kolejną próbę około 1 minutę, 5 minut, 30 minut, 2 godziny, 6 godzin i 24 godziny później, a po siódmej próbie dostarczenie zostaje porzucone. Każda próba jest podpisywana ponownie ze świeżym t, a adres URL musi być publiczny HTTPS, sprawdzany przy zapisie i ponownie przed każdą wysyłką. Dostarczenia idą od najstarszego, ale ponawiane mogą dotrzeć po nowszych, więc sortuj według znaczników czasu Meta.
W trybie bezpośrednim ponawianiem zajmuje się Meta: wszystko poza HTTP 200 jest ponawiane z malejącą częstotliwością przez do 7 dni, a te ponowienia mogą powtórzyć wiadomość. W obu trybach deduplikuj po identyfikatorze wiadomości Meta, ponieważ zmiana ponownie dostarczona przez Meta jest przekazywana ponownie pod nowym identyfikatorem dostarczenia.
Skąd endpoint bezpośredni wie, że POST jest prawdziwy?
Nie z X-Hub-Signature-256. Meta podpisuje kluczem aplikacji, która jest właścicielem subskrypcji, a dla numeru podłączonego tutaj jest to klucz easyCoexistence, który nie jest udostępniany, więc sprawdzanie tego nagłówka Twoim sekretem aplikacji Meta odrzuca prawdziwe dostarczenia. Token weryfikacyjny potwierdza endpoint tylko raz, podczas uścisku GET Meta. Zamiast tego działa:
- Umieść 32 lub więcej losowych znaków w ścieżce adresu callback i odrzucaj żądania bez nich; by zmienić, zapisz nowy URL.
- Użyj ogólnego odbiorcy, na przykład węzła Webhook w n8n, a nie wyzwalacza WhatsApp, który wymaga Twojej aplikacji Meta.
- Pobieraj media po identyfikatorze z Meta tokenem numeru, więc podrobiony identyfikator po prostu się nie powiedzie.
- Na własnych serwerach opcjonalnie zezwól tylko na sieć Meta, czyli trasy ogłaszane przez AS32934.
- Lub przełącz na tryb zarządzany z Forward URL, gdzie X-EC-Signature potwierdza każdy POST.
Typowe błędy
- Podłączanie kodu napisanego pod kopertę Meta do Forward URL bez zmian. Przekazanie zawiera jedną zmianę: czytaj event i value, a nie object, entry i changes.
- Czekanie na X-EC-Event o wartości statuses. Statusy dostarczenia przychodzą w zdarzeniach messages, w value.statuses, a odpowiedzi wpisane w aplikacji przychodzą jako smb_message_echoes.
- Wykonywanie pracy przed odpowiedzią. Przekazanie czeka 10 sekund, potem to samo dostarczenie wraca z nowym t; najpierw odpowiedz 2xx, a przetwarzaj z kolejki.
- Przełączenie na tryb zarządzany i założenie, że stary adres nadal odbiera. Cel bezpośredni zostaje usunięty w tej chwili; przekaż forward_url w tym samym wywołaniu set_inbound_mode.
easyCoexistence łączy numer aplikacji WhatsApp Business z Cloud API Meta przez Coexistence i pozwala wybrać dla każdego numeru, dokąd trafiają jego wiadomości: prosto od Meta na Twój serwer albo przez easyCoexistence, gdzie automatyzacje mogą odpowiadać, a podpisana kopia trafia na Forward URL. Monitorowanie i powiadomienia działają w obu trybach. US$ 9 do US$ 0.75 za numer miesięcznie, spadając w miarę dodawania numerów, z bezpłatnym okresem próbnym na pierwsze 3 dni.
Najczęściej zadawane pytania
Czy mój serwer zobaczy, co odpowiedziała automatyzacja?
Nie treść. Meta raportuje wysyłki z API jako statusy (sent, delivered, read) wewnątrz zdarzeń messages, z identyfikatorem wiadomości; sama treść jest w dzienniku uruchomień automatyzacji, przechowywanym 30 dni w zakładce Runs, oraz w Conversations przez czas, który wybrałeś.
Jak zmienić sekret przekazywania?
Kliknij Nowy sekret na stronie numeru albo wywołaj set_inbound_mode z rotate_secret ustawionym na true. Nowy sekret jest pokazany raz i od tej chwili podpisuje wszystko, także ponowienia starszych dostarczeń, więc od razu zaktualizuj swój serwer.
Czy Forward URL wymaga uścisku GET od Meta?
Nie. Tylko cel bezpośredni jest wywoływany przez Meta i musi odesłać hub.challenge. Forward URL wywołuje easyCoexistence i otrzymuje wyłącznie podpisane POST-y.
Czy numer może mieć jednocześnie cel bezpośredni i Forward URL?
Nie. Forward URL działa tylko wtedy, gdy numer jest zarządzany, a zapisanie celu bezpośredniego czyni go bezpośrednim. Forward URL i jego sekret są zachowane, więc powrót do trybu zarządzanego wznawia przekazywanie.
Czytaj dalej
Gotowy, aby zacząć?
Skonfiguruj WhatsApp Coexistence w kilka minut, nie miesięcy. Aplikacja nadal działa na telefonie.
Rozpocznij bezpłatny okres próbnyZweryfikowano w