Miten WhatsApp-viestit tulevat palvelimellesi: suora tai hallittu, ja allekirjoituksen tarkistus
Jokaisella easyCoexistencen kautta yhdistetyllä numerolla on yksi saapuvan viestin tila. Suoraan järjestelmääsi (suora): Meta lähettää webhookit HTTPS-päätepisteeseesi, URL:ssa oleva salaisuus toimii tunnistetietona ja automaatiot ovat pois päältä. easyCoexistencen kautta (hallittu): Meta toimittaa viestit easyCoexistencelle, automaatiot voivat vastata, ja valinnainen Forward URL saa Metan alkuperäisen arvon yhteystietoineen, allekirjoitettuna X-EC-Signature-otsakkeella, jonka voit tarkistaa.
Yrityksiä per välitetty toimitus, 1 min, 5 min, 30 min, 2 h, 6 h ja 24 h välein, noin 33 tuntia yhteensä.
Kuinka kauan kukin välityksen yritys odottaa 2xx-vastausta ennen kuin se lasketaan epäonnistuneeksi.
Suositeltu raja allekirjoituksen t:n iälle; uudelleenyritykset allekirjoitetaan uudelleen, joten aidot toimitukset pysyvät rajan sisällä.
Kuinka kauan Meta yrittää uudelleen suoraa webhookia, joka sai muun kuin HTTP 200 -vastauksen, mikä voi toistaa viestejä.
Suurin Metan lähettämä webhookin payload, historiapalat mukaan lukien.
Ajolokit, jotka säilytetään hallitulle numerolle viesti- ja vastaustekstineen; viestiteksti itsessään säilytetään 30, 90 tai 365 päivää valintasi mukaan.
Mikä on ero suoran ja hallitun välillä?
Se, mistä Meta toimittaa numeron viestien webhookit. Hallittu, näkyy tilana Through easyCoexistence, tarkoittaa, että Meta toimittaa easyCoexistencelle, joka tarkistaa Metan allekirjoituksen, ajaa automaatiot, säilyttää keskustelut Conversations-näkymää varten ja, jos asetat Forward URL:n, välittää jokaisen Metan muutoksen eteenpäin allekirjoitettuna salaisuudella, jonka vain sinä tunnet. Suora, näkyy tilana Straight to your system, tarkoittaa, että easyCoexistence asettaa HTTPS-päätepisteesi numeron WhatsApp Business -tilin webhook-ohitukseksi, jolloin Meta lähettää suoraan sinulle eivätkä viestit koskaan kulje easyCoexistencen kautta.
Valvontaan liittyvät operatiiviset webhookit, kuten account_update ja laatumuutokset, pysyvät easyCoexistencella molemmissa tiloissa, joten hälytykset toimivat kummassakin tapauksessa.
| 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 |
Miten vaihdat numeron tilasta toiseen?
Numeron sivulla kortti Where incoming messages go näyttää tilan kahtena vaihtoehtona, Through easyCoexistence ja Straight to your system. Webhook-kohteen tallentaminen kortista Route incoming messages to your own webhook tai funktiolla set_webhook_destination tekee numerosta suoran. Valinta Through easyCoexistence poistaa kohteen Metalta heti, joten lisää sama URL Forward URL:ksi, jotta vastaanotto jatkuu. Jonossa olevat välitykset pudotetaan, kun numero poistuu hallitusta tilasta, ja ilman webhook-URL:ia yhdistetyt numerot alkavat hallittuina.
Tekoälystäsi set_inbound_mode vaihtaa tilan ja asettaa välityksen yhdellä kutsulla ja palauttaa välityssalaisuuden kerran:
// 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
}Mitä välitetty POST sisältää?
Yksi Metan muutos per pyyntö, käärittynä eikä Metan object-, entry- ja changes-rakenteena. id on toimitustunnus, joka toistuu X-EC-Delivery-otsakkeessa ja pysyy samana uudelleenyrityksissä. event on Metan kenttänimi: messages, smb_message_echoes, history tai smb_app_state_sync, ja se toistuu X-EC-Event-otsakkeessa. received_at on hetki, jolloin easyCoexistence sai muutoksen Metalta, connection tunnistaa numeron, ja value on täsmälleen se, mitä Meta lähetti, joten Metan payloadille kirjoitettu jäsennyskoodi toimii sillä sellaisenaan. Toimitustilat tulevat messages-tapahtumien sisällä kohdassa 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?" }
}]
}
}Miten tarkistat X-EC-Signature Node.js:ssä?
Lue otsake muodossa t=<unix-sekunnit>,v1=<64 heksamerkkiä>. Hylkää t, joka on yli 5 minuuttia kellostasi, laske HMAC-SHA256 merkkijonosta t, piste ja raaka runko, avaimena koko välityssalaisuus UTF-8-tekstinä, ja vertaa tulosta v1:een vakioajassa. Vasta sitten jäsennä JSON. Vastaa 2xx 10 sekunnin sisällä ja tee työ jälkikäteen, ja muista hyväksymiesi toimitusten tunnukset, jotta uudelleenyritystä ei käsitellä kahdesti.
// 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);Miten tarkistat sen Pythonissa?
Samat neljä tarkistusta standardikirjaston avulla: tiukka otsakemalli, t:n ikä, hmac.new laskee t:n, pisteen ja raakojen bytejen yli sekä hmac.compare_digest. FastAPI:ssa raaka runko tulee odotuksella await request.body(), ja BackgroundTasks ajaa työn 200-vastauksen lähettämisen jälkeen. Flaskissa käytä request.get_data()-funktiota, äläkä koskaan rakenna runkoa uudelleen json.dumps-kutsulla, koska Pythonin oletuserottimet lisäävät välilyöntejä eikä allekirjoitus enää täsmää.
# 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)Miten epäonnistuneet toimitukset yritetään uudelleen?
Välitys on toimitettu, kun päätepisteesi vastaa minkä tahansa 2xx-vastauksen 10 sekunnin sisällä. Mikä tahansa muu, aikakatkaisu, 4xx, 5xx tai uudelleenohjaus, jota ei seurata, ajastaa seuraavan yrityksen noin 1 minuutin, 5 minuutin, 30 minuutin, 2 tunnin, 6 tunnin ja 24 tunnin päähän, ja seitsemännen yrityksen jälkeen toimitus hylätään. Jokainen yritys allekirjoitetaan uudelleen tuoreella t:llä, ja URL:n on oltava julkinen HTTPS, tarkistettuna tallennettaessa ja ennen jokaista lähetystä. Toimitukset lähtevät vanhimmasta uusimpaan, mutta uudelleen yritetty voi saapua uudempien jälkeen, joten järjestä Metan aikaleimojen mukaan.
Suoralla kohteella uudelleenyrityksistä huolehtii Meta: mikä tahansa muu kuin HTTP 200 yritetään uudelleen harvenevin välein jopa 7 päivää, ja nämä uudelleenyritykset voivat toistaa viestin. Deduplikoi Metan viestitunnuksen perusteella molemmissa tiloissa, sillä Metan uudelleen toimittama muutos välitetään uudelleen uudella toimitustunnuksella.
Miten suora päätepiste tietää, että POST on aito?
Ei X-Hub-Signature-256-otsakkeesta. Meta allekirjoittaa sovelluksen sovellussalaisuudella, joka omistaa tilauksen. Tähän easyCoexistencen kautta yhdistettyyn numeroon se on easyCoexistencen eikä sitä jaeta, joten oman Meta-sovelluksesi salaisuudella tarkistaminen hylkää aidot toimitukset. Varmennustunniste todistaa päätepisteen vain kerran Metan GET-kättelyssä. Sen sijaan toimii seuraava:
- Lisää callback-URL:n polkuun vähintään 32 satunnaista merkkiä ja hylkää pyynnöt ilman niitä; vaihtaaksesi tallenna uusi URL.
- Käytä yleistä vastaanotinta, kuten n8n:n Webhook-solmua, älä WhatsApp-käynnistintä, joka odottaa omaa Meta-sovellustasi.
- Lataa media id:n perusteella Metalta numeron tunnuksella, jolloin väärennetty id yksinkertaisesti epäonnistuu.
- Itse ylläpidetyillä palvelimilla voit halutessasi sallia vain Metan verkon, AS32934:n ilmoittamat reitit.
- Tai vaihda hallittuun tilaan Forward URL:lla, jolloin X-EC-Signature todistaa jokaisen POST-pyynnön.
Yleiset virheet
- Koodin, joka on kirjoitettu Metan kuorelle, osoittaminen Forward URL:iin muuttamattomana. Välitys sisältää yhden muutoksen: lue event ja value, ei object-, entry- ja changes-rakennetta.
- Odotetaan X-EC-Event-arvoa statuses. Toimitustilat tulevat messages-tapahtumien sisällä kohdassa value.statuses, ja sovelluksessa kirjoitetut vastaukset tulevat smb_message_echoes-tapahtumina.
- Työn tekeminen ennen vastaamista. Välitys odottaa 10 sekuntia, minkä jälkeen sama toimitus tulee takaisin uudella t:llä; vastaa ensin 2xx ja käsittele sitten jonosta.
- Siirtyminen hallittuun ja oletus, että vanha URL vastaanottaa edelleen. Suora kohde poistetaan juuri silloin; anna forward_url samassa set_inbound_mode-kutsussa.
easyCoexistence yhdistää WhatsApp Business -sovelluksen numeron Metan Cloud API -rajapintaan Coexistencen kautta ja antaa valita numeroittain, minne viestit menevät: suoraan Metalta palvelimellesi tai easyCoexistencen kautta, jolloin automaatiot voivat vastata ja allekirjoitettu kopio menee Forward URL:iin. Valvonta ja hälytykset toimivat molemmissa tiloissa. Hinta alkaen US$ 9 numeroa kohden kuukaudessa, laskien US$ 0.75:een numeroiden lisääntyessä, ja ensimmäiset 3 päivää ovat ilmaista kokeilua.
Usein kysytyt kysymykset
Näkeekö palvelimeni, mitä automaatio vastasi?
Ei tekstiä. Meta raportoi API-lähetykset tiloina (sent, delivered, read) messages-tapahtumien sisällä viestitunnuksen kanssa; itse teksti on automaation ajolokissa, joka säilytetään 30 päivää Runs-välilehdellä, sekä Conversations-näkymässä valitsemasi ajan.
Miten vaihdan välityssalaisuuden?
Napsauta numeron sivulla New secret tai kutsu set_inbound_mode-funktiota arvolla rotate_secret true. Uusi salaisuus näytetään kerran ja allekirjoittaa kaiken tästä eteenpäin, myös vanhempien toimitusten uudelleenyritykset, joten päivitä palvelimesi heti.
Tarvitseeko Forward URL Metan GET-kättelyn?
Ei. Vain suora kohde on Metan kutsuma, ja sen on palautettava hub.challenge-arvo. Forward URL:n kutsuu easyCoexistence, ja se vastaanottaa vain allekirjoitettuja POST-pyyntöjä.
Voiko numerolla olla samanaikaisesti suora kohde ja Forward URL?
Ei. Forward URL toimii vain, kun numero on hallittu, ja suoran kohteen tallentaminen tekee numerosta suoran. Forward URL ja sen salaisuus säilytetään, joten palaaminen hallittuun tilaan jatkaa välitystä.
Lue lisää
Valmis aloittamaan?
Ota WhatsApp Coexistence käyttöön minuuteissa, ei kuukausissa. Sovellus toimii edelleen puhelimessa.
Aloita ilmainen kokeiluVahvistettu