Hoe WhatsApp-berichten je server bereiken: direct of beheerd, en de handtekening verifiëren
Elk gekoppeld nummer heeft via easyCoexistence één inkomende modus. Rechtstreeks naar je systeem (direct): Meta stuurt zijn webhooks naar je HTTPS-endpoint, een geheim in de URL is het toegangsgeheim, en automatiseringen staan uit. Via easyCoexistence (beheerd): Meta levert aan easyCoexistence, automatiseringen kunnen antwoorden, en een optionele Forward URL ontvangt Meta's oorspronkelijke waarde met verbindingsgegevens, ondertekend met X-EC-Signature zodat jij kunt verifiëren.
Pogingen per doorgestuurde levering, met 1 min, 5 min, 30 min, 2 h, 6 h en 24 h ertussen, in totaal ongeveer 33 uur.
Hoe lang elke doorstuurpoging wacht op een 2xx voordat die als mislukt geldt.
Aanbevolen limiet voor de leeftijd van de t in de handtekening; nieuwe pogingen worden opnieuw ondertekend, zodat echte leveringen binnen die limiet blijven.
Hoe lang Meta een directe webhook opnieuw probeert als die iets anders dan HTTP 200 kreeg, wat berichten kan herhalen.
Grootste webhook-payload die Meta verstuurt, history-chunks inbegrepen.
Runlogs van een beheerd nummer, met bericht- en antwoordtekst; de berichttekst zelf wordt 30, 90 of 365 dagen bewaard, naar keuze.
Wat is het verschil tussen direct en beheerd?
Waar Meta de berichtwebhooks van het nummer levert. Beheerd, aangeduid als Via easyCoexistence, betekent dat Meta levert aan easyCoexistence, dat Meta's handtekening controleert, je automatiseringen uitvoert, de chats bewaart voor Conversations en, als je een Forward URL instelt, elke wijziging van Meta doorgeeft aan jou, ondertekend met een geheim dat alleen jij bezit. Direct, aangeduid als Rechtstreeks naar je systeem, betekent dat easyCoexistence je HTTPS-endpoint instelt als webhook-override op het WhatsApp Business Account van het nummer, zodat Meta rechtstreeks naar jou post en de berichten nooit easyCoexistence bereiken.
De operationele webhooks achter monitoring, zoals account_update en kwaliteitswijzigingen, blijven in beide modi bij easyCoexistence, daarom blijven waarschuwingen in beide gevallen werken.
| 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 |
Hoe zet je een nummer om tussen de twee?
Op de pagina van het nummer toont de kaart Waar inkomende berichten heen gaan de modus als twee keuzes, Via easyCoexistence en Rechtstreeks naar je systeem. Een webhookbestemming opslaan, in de kaart Inkomende berichten naar je eigen webhook of met set_webhook_destination, maakt het nummer direct. Via easyCoexistence kiezen verwijdert die bestemming meteen bij Meta, dus voeg dezelfde URL toe als Forward URL om te blijven ontvangen. Wachtende doorsturingen vervallen wanneer een nummer de beheerde modus verlaat, en nummers die zonder webhook-URL zijn gekoppeld, starten beheerd.
Vanuit je AI schakelt set_inbound_mode de modus en stelt de doorsturing in één aanroep in, en geeft het doorstuursecret één keer terug:
// 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
}Wat bevat een doorgestuurde POST?
Eén wijziging van Meta per verzoek, verpakt, in plaats van Meta's object-, entry- en changes-envelop. id is het leverings-id, herhaald in X-EC-Delivery en stabiel over nieuwe pogingen. event is de naam van het Meta-veld, messages, smb_message_echoes, history of smb_app_state_sync, herhaald in X-EC-Event. received_at is wanneer easyCoexistence de wijziging van Meta ontving, connection geeft het nummer aan, en value is precies wat Meta verstuurde, zodat parsecode die voor Meta's payload is geschreven op deze waarde werkt. Leveringsstatussen komen binnen in messages-events, onder 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?" }
}]
}
}Hoe verifieer je X-EC-Signature in Node.js?
Lees de header als t=<unix seconden>,v1=<64 hexadecimale tekens>. Weiger een t die meer dan 5 minuten van je klok afwijkt, bereken HMAC-SHA256 over t, een punt en de ruwe body, met als sleutel het volledige doorstuursecret als UTF-8-tekst, en vergelijk het resultaat met v1 in constante tijd. Pas dan parseer je de JSON. Antwoord binnen 10 seconden met 2xx en doe het werk daarna, en onthoud de leverings-id's die je hebt geaccepteerd, zodat een nieuwe poging niet twee keer wordt verwerkt.
// 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);Hoe verifieer je het in Python?
Dezelfde vier controles met de standaardbibliotheek: een strikt patroon voor de header, de leeftijd van t, hmac.new over t, een punt en de ruwe bytes, en hmac.compare_digest. In FastAPI komt de ruwe body van await request.body(), en BackgroundTasks voert het werk uit nadat de 200 is verzonden. In Flask gebruik je request.get_data(), en bouw je de body nooit opnieuw op met json.dumps, want Pythons standaardscheidingstekens voegen spaties toe en dan klopt de handtekening niet meer.
# 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)Hoe worden mislukte leveringen opnieuw geprobeerd?
Een doorsturing telt als geleverd wanneer je endpoint binnen 10 seconden een willekeurige 2xx antwoordt. Al het andere, een time-out, een 4xx, een 5xx of een redirect die niet wordt gevolgd, plant de volgende poging ongeveer 1 minuut, 5 minuten, 30 minuten, 2 uur, 6 uur en 24 uur later, en na de zevende poging wordt de levering opgegeven. Elke poging wordt opnieuw ondertekend met een nieuwe t. De URL moet publiek HTTPS zijn; dat wordt gecontroleerd bij het opslaan en opnieuw vóór elke verzending. Leveringen gaan het oudst eerst weg, maar een opnieuw geprobeerde kan na nieuwere aankomen, dus sorteer op Meta's tijdstempels.
Bij een directe bestemming doet Meta het opnieuw proberen: alles behalve HTTP 200 wordt met afnemende frequentie tot 7 dagen opnieuw geprobeerd, en die nieuwe pogingen kunnen een bericht herhalen. Dedupliceer op Meta's bericht-id in beide modi, want een wijziging die Meta opnieuw levert, wordt doorgestuurd onder een nieuw leverings-id.
Hoe weet een directe endpoint dat een POST echt is?
Niet aan de hand van X-Hub-Signature-256. Meta ondertekent met het app-geheim van de app die het abonnement bezit. Voor een hier gekoppeld nummer is dat easyCoexistence's geheim, dat niet wordt gedeeld, dus controleer je die header met je eigen Meta app-geheim, dan wijs je echte leveringen af. Het verify token bewijst het endpoint maar één keer, tijdens Meta's GET-handshake. Wat wel werkt:
- Zet 32 of meer willekeurige tekens in het pad van de callback-URL en weiger verzoeken zonder die tekens; om te roteren, sla een nieuwe URL op.
- Gebruik een generieke ontvanger, zoals de n8n Webhook-node, geen WhatsApp-trigger die je eigen Meta-app verwacht.
- Download media op id bij Meta met het token van het nummer, zodat een vervalst id gewoon mislukt.
- Op zelfgehoste servers kun je optioneel alleen het netwerk van Meta toestaan, de routes aangekondigd door AS32934.
- Of schakel over naar beheerd met een Forward URL, waar X-EC-Signature elke POST bewijst.
Veelgemaakte fouten
- Code die voor Meta's envelop is geschreven ongewijzigd op de Forward URL richten. Een doorsturing bevat één wijziging: lees event en value, niet object, entry en changes.
- Wachten op een X-EC-Event van statuses. Leveringsstatussen komen binnen in messages-events, in value.statuses, en antwoorden die in de app zijn getypt, komen als smb_message_echoes.
- Het werk doen voordat je antwoordt. Een doorsturing wacht 10 seconden, daarna komt dezelfde levering terug met een nieuwe t; antwoord eerst met 2xx en verwerk vanuit een wachtrij.
- Overschakelen naar beheerd en aannemen dat de oude URL nog ontvangt. De directe bestemming wordt op dat moment verwijderd; geef forward_url mee in dezelfde set_inbound_mode-aanroep.
easyCoexistence koppelt een WhatsApp Business-app-nummer aan de Cloud API van Meta via Coexistence en laat je per nummer kiezen waar de berichten naartoe gaan: rechtstreeks van Meta naar je server, of via easyCoexistence, zodat automatiseringen kunnen antwoorden en een ondertekende kopie bij je Forward URL aankomt. Monitoring en waarschuwingen werken in beide modi. US$ 9 tot US$ 0.75 per gekoppeld nummer per maand, dalend naarmate je meer nummers toevoegt, met de eerste 3 dagen gratis.
Veelgestelde vragen
Ziet mijn server wat een automatisering heeft geantwoord?
Niet de tekst. Meta meldt API-verzendingen als statussen (sent, delivered, read) binnen messages-events, met het bericht-id; de tekst zelf staat in het runlog van de automatisering, 30 dagen bewaard op het tabblad Runs, en in Conversations voor de tijd die je hebt gekozen.
Hoe roteer ik het doorstuursecret?
Klik op Nieuw geheim op de pagina van het nummer, of roep set_inbound_mode aan met rotate_secret op true. Het nieuwe geheim wordt één keer getoond en ondertekent alles vanaf dat moment, ook de nieuwe pogingen van oudere leveringen, dus werk je server meteen bij.
Heeft een Forward URL de GET-handshake van Meta nodig?
Nee. Alleen een directe bestemming wordt door Meta aangeroepen en moet hub.challenge teruggeven. Een Forward URL wordt door easyCoexistence aangeroepen en ontvangt alleen ondertekende POST's.
Kan een nummer tegelijk een directe bestemming en een Forward URL hebben?
Nee. Een Forward URL werkt alleen zolang het nummer beheerd is, en een directe bestemming opslaan maakt het direct. De Forward URL en het geheim blijven bewaard, dus terugschakelen naar beheerd hervat de doorsturing.
Lees verder
Klaar om te beginnen?
Stel WhatsApp Coexistence in enkele minuten in, niet maanden. De app blijft op je telefoon werken.
Start je gratis proefperiodeGeverifieerd op