How WhatsApp messages reach your server: direct or managed, and verifying the signature
Each number connected through easyCoexistence has one inbound mode. Straight to your system (direct): Meta posts its webhooks to your HTTPS endpoint, a secret in the URL is the credential, and automations are off. Through easyCoexistence (managed): Meta delivers to easyCoexistence, automations can answer, and an optional Forward URL gets Meta's original value with connection details, signed with X-EC-Signature for you to verify.
Tries per forwarded delivery, spaced 1 min, 5 min, 30 min, 2 h, 6 h and 24 h apart, about 33 hours in all.
How long each forward attempt waits for a 2xx before it counts as failed.
Suggested limit on the age of the signature's t; retries are signed again, so genuine deliveries stay inside it.
How long Meta retries a direct webhook that got anything but HTTP 200, which can repeat messages.
Largest webhook payload Meta sends, history chunks included.
Run logs kept for a managed number, with message and reply text; message text itself is kept 30, 90 or 365 days, your choice.
What is the difference between direct and managed?
Where Meta delivers the number's message webhooks. Managed, shown as Through easyCoexistence, means Meta delivers to easyCoexistence, which checks Meta's signature, runs your automations, keeps the chats for Conversations and, if you set a Forward URL, passes each Meta change on to you signed with a secret only you hold. Direct, shown as Straight to your system, means easyCoexistence sets your HTTPS endpoint as the webhook override on the number's WhatsApp Business Account, so Meta posts straight to you and the messages never reach easyCoexistence.
The operational webhooks behind monitoring, such as account_update and quality changes, stay with easyCoexistence in both modes, which is why alerts keep working either way.
| 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 |
How do you switch a number between the two?
On the number's page, the Where incoming messages go card shows the mode as two choices, Through easyCoexistence and Straight to your system. Saving a webhook destination, in the Route incoming messages to your own webhook card or with set_webhook_destination, makes the number direct. Choosing Through easyCoexistence removes that destination at Meta at once, so add the same URL as the Forward URL to keep receiving. Queued forwards are dropped when a number leaves managed mode, and numbers connected without a webhook URL start managed.
From your AI, set_inbound_mode switches the mode and sets the forward in one call, and returns the forward secret once:
// 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
}What does a forwarded POST contain?
One Meta change per request, wrapped, rather than Meta's object, entry and changes envelope. id is the delivery id, repeated in X-EC-Delivery and stable across retries. event is the Meta field name, messages, smb_message_echoes, history or smb_app_state_sync, repeated in X-EC-Event. received_at is when easyCoexistence got the change from Meta, connection identifies the number, and value is exactly what Meta sent, so parsing code written for Meta's payload works on it. Delivery statuses arrive inside messages events, under 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?" }
}]
}
}How do you verify X-EC-Signature in Node.js?
Read the header as t=<unix seconds>,v1=<64 hex characters>. Reject a t more than 5 minutes from your clock, compute HMAC-SHA256 over t, a dot and the raw body, keyed with the whole forward secret as UTF-8 text, and compare the result with v1 in constant time. Only then parse the JSON. Answer 2xx within 10 seconds and do the work afterwards, and remember the delivery ids you have accepted so a retry is not processed twice.
// 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);How do you verify it in Python?
The same four checks with the standard library: a strict pattern for the header, the age of t, hmac.new over t, a dot and the raw bytes, and hmac.compare_digest. In FastAPI the raw body comes from await request.body(), and BackgroundTasks runs the work after the 200 is sent. In Flask, use request.get_data(), and never rebuild the body with json.dumps, because Python's default separators add spaces and the signature no longer matches.
# 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)How are failed deliveries retried?
A forward counts as delivered when your endpoint answers any 2xx within 10 seconds. Anything else, a timeout, a 4xx, a 5xx or a redirect, which is not followed, schedules the next attempt about 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 24 hours later, and after the seventh attempt the delivery is abandoned. Each attempt is signed again with a fresh t, and the URL must be public HTTPS, checked when it is saved and again before every send. Deliveries go out oldest first, but a retried one can land after newer ones, so order by Meta's timestamps.
On a direct destination Meta does the retrying: anything but HTTP 200 is retried with decreasing frequency for up to 7 days, and those retries can repeat a message. Deduplicate on Meta's message id in both modes, since a change Meta redelivers is forwarded again under a new delivery id.
How does a direct endpoint know a POST is genuine?
Not from X-Hub-Signature-256. Meta signs with the app secret of the app that owns the subscription, which for a number connected here is easyCoexistence's and is not shared, so checking that header with your own Meta app secret rejects genuine deliveries. The verify token only proves the endpoint once, during Meta's GET handshake. What works instead:
- Put 32 or more random characters in the callback URL path and reject requests without them; to rotate, save a new URL.
- Use a generic receiver, such as the n8n Webhook node, not a WhatsApp trigger that expects your own Meta app.
- Download media by id from Meta with the number's token, so a forged id simply fails.
- On self-hosted servers, optionally allow only Meta's network, the routes announced by AS32934.
- Or switch to managed with a Forward URL, where X-EC-Signature proves each POST.
Common mistakes
- Pointing code written for Meta's envelope at the Forward URL unchanged. A forward carries one change: read event and value, not object, entry and changes.
- Waiting for an X-EC-Event of statuses. Delivery statuses come inside messages events, in value.statuses, and replies typed in the app come as smb_message_echoes.
- Doing the work before answering. A forward waits 10 seconds, then the same delivery comes back with a new t; answer 2xx first and process from a queue.
- Switching to managed and assuming the old URL still receives. The direct destination is removed at that moment; pass forward_url in the same set_inbound_mode call.
easyCoexistence connects a WhatsApp Business app number to Meta's Cloud API through Coexistence and lets you choose, per number, where its messages go: straight from Meta to your server, or through easyCoexistence so automations can answer and a signed copy reaches your Forward URL. Monitoring and alerts work in both modes. US$ 9 down to US$ 0.75 per number per month, falling as you add numbers, with the first 3 days free.
easyCoexistence is a multichannel API and MCP server that connects AI agents such as Claude and ChatGPT to WhatsApp, Instagram, TikTok, Facebook and more. On WhatsApp it uses Coexistence: the business keeps using its number in the WhatsApp Business app while the AI works through Meta's official API.
Frequently asked questions
Will my server see what an automation replied?
Not the text. Meta reports API sends as statuses (sent, delivered, read) inside messages events, with the message id; the text itself is in the automation's run log, kept 30 days in the Runs tab, and in Conversations for the time you chose.
How do I rotate the forward secret?
Click New secret on the number's page, or call set_inbound_mode with rotate_secret set to true. The new secret is shown once and signs everything from then on, retries of older deliveries included, so update your server right away.
Does a Forward URL need Meta's GET handshake?
No. Only a direct destination is called by Meta and has to echo hub.challenge. A Forward URL is called by easyCoexistence and receives signed POSTs only.
Can a number have a direct destination and a Forward URL at once?
No. A Forward URL works only while the number is managed, and saving a direct destination makes it direct. The Forward URL and its secret are kept, so switching back to managed resumes forwarding.
Keep reading
Ready to get started?
Set up WhatsApp Coexistence in minutes, not months. The app keeps working on the phone.
Start Free TrialVerified on