Wie WhatsApp-Nachrichten Ihren Server erreichen: direkt oder verwaltet, und die Signatur prüfen
Jede über easyCoexistence verbundene Nummer hat einen eingehenden Modus. Direkt an Ihr System: Meta sendet seine Webhooks an Ihren HTTPS-Endpoint, ein Geheimnis in der URL dient als Zugangsdaten, und Automations sind ausgeschaltet. Über easyCoexistence (verwaltet): Meta liefert an easyCoexistence, Automations können antworten, und eine optionale Forward URL erhält Metas ursprünglichen Wert mit Verbindungsdetails, signiert mit X-EC-Signature, damit Sie ihn prüfen können.
Versuche pro weitergeleiteter Zustellung, zeitlich versetzt nach 1 Min., 5 Min., 30 Min., 2 Std., 6 Std. und 24 Std., insgesamt rund 33 Stunden.
Wie lange jeder Weiterleitungsversuch auf eine 2xx-Antwort wartet, bevor er als fehlgeschlagen gilt.
Empfohlene Grenze für das Alter des t der Signatur. Wiederholungen werden erneut signiert, sodass echte Zustellungen innerhalb bleiben.
Wie lange Meta einen direkten Webhook wiederholt, der etwas anderes als HTTP 200 erhalten hat, was Nachrichten doppelt senden kann.
Größte Webhook-Payload, die Meta sendet, einschließlich Verlaufsblöcken.
Laufprotokolle, die für eine verwaltete Nummer mit Nachrichten- und Antworttext gespeichert werden. Der Nachrichtentext selbst wird 30, 90 oder 365 Tage aufbewahrt, nach Ihrer Wahl.
Was ist der Unterschied zwischen direkt und verwaltet?
Wohin Meta die Nachrichten-Webhooks der Nummer zustellt. Verwaltet, angezeigt als „Through easyCoexistence“, bedeutet: Meta liefert an easyCoexistence, das die Signatur von Meta prüft, Ihre Automations ausführt, die Chats für Conversations speichert und, wenn Sie eine Forward URL festlegen, jede Änderung von Meta signiert an Sie weitergibt, mit einem Geheimnis, das nur Sie besitzen. Direkt, angezeigt als „Straight to your system“, bedeutet: easyCoexistence setzt Ihren HTTPS-Endpoint als Webhook-Override auf dem WhatsApp Business Account der Nummer. Meta sendet dann direkt an Sie, und die Nachrichten erreichen easyCoexistence nie.
Die betrieblichen Webhooks hinter dem Monitoring, etwa account_update und Qualitätsänderungen, bleiben in beiden Modi bei easyCoexistence. Deshalb funktionieren Warnmeldungen in jedem Fall weiter.
| 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 |
Wie wechseln Sie eine Nummer zwischen beiden?
Auf der Seite der Nummer zeigt die Karte „Where incoming messages go“ den Modus als zwei Optionen an, „Through easyCoexistence“ und „Straight to your system“. Das Speichern eines Webhook-Ziels, in der Karte „Route incoming messages to your own webhook“ oder mit set_webhook_destination, macht die Nummer direkt. Wenn Sie „Through easyCoexistence“ wählen, wird dieses Ziel bei Meta sofort entfernt. Tragen Sie deshalb dieselbe URL als Forward URL ein, um weiter Nachrichten zu erhalten. Wartende Weiterleitungen werden verworfen, wenn eine Nummer den verwalteten Modus verlässt. Nummern, die ohne Webhook-URL verbunden wurden, starten verwaltet.
Über Ihre KI setzt set_inbound_mode den Modus und die Weiterleitung in einem Aufruf und gibt das Forward-Geheimnis einmalig zurück:
// 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
}Was enthält ein weitergeleiteter POST?
Eine Änderung von Meta pro Anfrage, verpackt, statt der Meta-Hülle aus object, entry und changes. id ist die Zustell-ID, die in X-EC-Delivery wiederholt wird und über Wiederholungen hinweg gleich bleibt. event ist der Meta-Feldname, also messages, smb_message_echoes, history oder smb_app_state_sync, und wird in X-EC-Event wiederholt. received_at ist der Zeitpunkt, zu dem easyCoexistence die Änderung von Meta erhalten hat. connection kennzeichnet die Nummer. value ist genau das, was Meta gesendet hat, sodass Code, der Metas Payload auswertet, damit unverändert funktioniert. Zustellstatus kommen innerhalb von messages-Ereignissen unter 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?" }
}]
}
}Wie überprüfen Sie X-EC-Signature in Node.js?
Lesen Sie den Header als t=<Unix-Sekunden>,v1=<64 Hexzeichen>. Lehnen Sie ein t ab, das mehr als 5 Minuten von Ihrer Uhr entfernt ist. Berechnen Sie HMAC-SHA256 über t, einen Punkt und den rohen Body, mit dem vollständigen Forward-Geheimnis als UTF-8-Text als Schlüssel. Vergleichen Sie das Ergebnis mit v1 in konstanter Zeit. Erst danach parsen Sie das JSON. Antworten Sie innerhalb von 10 Sekunden mit 2xx und erledigen Sie die Arbeit danach. Merken Sie sich außerdem die Zustell-IDs, die Sie angenommen haben, damit ein Wiederholungsversuch nicht doppelt verarbeitet wird.
// 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);Wie überprüfen Sie es in Python?
Dieselben vier Prüfungen mit der Standardbibliothek: ein strenges Muster für den Header, das Alter von t, hmac.new über t, einen Punkt und die rohen Bytes sowie hmac.compare_digest. In FastAPI stammt der rohe Body aus await request.body(), und BackgroundTasks führt die Arbeit nach dem gesendeten 200 aus. In Flask verwenden Sie request.get_data() und bauen den Body niemals mit json.dumps neu auf. Die Standard-Trennzeichen von Python fügen Leerzeichen hinzu, und die Signatur stimmt dann nicht mehr.
# 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)Wie werden fehlgeschlagene Zustellungen erneut versucht?
Eine Weiterleitung gilt als zugestellt, wenn Ihr Endpoint innerhalb von 10 Sekunden mit einer beliebigen 2xx-Antwort antwortet. Alles andere, also ein Timeout, ein 4xx, ein 5xx oder eine Weiterleitung, der nicht gefolgt wird, plant den nächsten Versuch etwa 1 Min., 5 Min., 30 Min., 2 Std., 6 Std. und 24 Std. später. Nach dem siebten Versuch wird die Zustellung aufgegeben. Jeder Versuch wird mit einem neuen t erneut signiert. Die URL muss öffentliches HTTPS sein, was beim Speichern und vor jedem Versand erneut geprüft wird. Zustellungen gehen der Reihe nach, die älteste zuerst. Eine wiederholte kann jedoch nach neueren ankommen, sortieren Sie daher nach den Zeitstempeln von Meta.
Bei einem direkten Ziel übernimmt Meta die Wiederholungen. Alles außer HTTP 200 wird mit abnehmender Häufigkeit bis zu 7 Tage lang wiederholt, und diese Wiederholungen können eine Nachricht doppelt senden. Deduplizieren Sie in beiden Modi anhand der Nachrichten-ID von Meta, denn eine Änderung, die Meta erneut zustellt, wird unter einer neuen Zustell-ID erneut weitergeleitet.
Woran erkennt ein direkter Endpoint, dass ein POST echt ist?
Nicht an X-Hub-Signature-256. Meta signiert mit dem App-Secret der App, die das Abonnement besitzt. Für eine hier verbundene Nummer ist das das App-Secret von easyCoexistence, und es wird nicht geteilt. Eine Prüfung dieses Headers mit Ihrem eigenen Meta-App-Secret würde deshalb echte Zustellungen ablehnen. Der Verify-Token bestätigt den Endpoint nur einmal, beim GET-Handshake von Meta. Was stattdessen funktioniert:
- Setzen Sie 32 oder mehr zufällige Zeichen in den Pfad der Callback-URL und lehnen Sie Anfragen ohne sie ab. Zum Rotieren speichern Sie eine neue URL.
- Verwenden Sie einen generischen Empfänger, etwa den n8n-Webhook-Knoten, und keinen WhatsApp-Trigger, der Ihre eigene Meta-App erwartet.
- Laden Sie Medien über die ID bei Meta mit dem Token der Nummer herunter, sodass eine gefälschte ID einfach fehlschlägt.
- Auf selbst gehosteten Servern können Sie optional nur das Netz von Meta zulassen, also die Routen, die von AS32934 angekündigt werden.
- Oder wechseln Sie mit einer Forward URL zu verwaltet, wo X-EC-Signature jeden POST belegt.
Häufige Fehler
- Code, der für Metas Envelope geschrieben wurde, unverändert an die Forward URL zu richten. Eine Weiterleitung enthält genau eine Änderung. Lesen Sie event und value, nicht object, entry und changes.
- Darauf zu warten, dass X-EC-Event den Wert statuses hat. Zustellstatus kommen innerhalb von messages-Ereignissen in value.statuses, und in der App getippte Antworten kommen als smb_message_echoes.
- Die Arbeit vor der Antwort zu erledigen. Eine Weiterleitung wartet 10 Sekunden, dann kommt dieselbe Zustellung mit neuem t zurück. Antworten Sie zuerst mit 2xx und verarbeiten Sie aus einer Warteschlange.
- Zu verwaltet zu wechseln und anzunehmen, dass die alte URL weiter empfängt. Das direkte Ziel wird in diesem Moment entfernt. Übergeben Sie forward_url im selben set_inbound_mode-Aufruf.
easyCoexistence verbindet eine WhatsApp-Business-App-Nummer über Coexistence mit der Cloud API von Meta. Pro Nummer legen Sie fest, wohin ihre Nachrichten gehen: direkt von Meta an Ihren Server oder über easyCoexistence, damit Automations antworten können und eine signierte Kopie Ihre Forward URL erreicht. Monitoring und Warnmeldungen funktionieren in beiden Modi. US$ 9 bis hinunter zu US$ 0.75 pro Nummer und Monat, sinkend mit jeder weiteren Nummer, mit einer kostenlosen Testphase von 3 Tagen.
Häufig gestellte Fragen
Sieht mein Server, was eine Automation geantwortet hat?
Nicht den Text. Meta meldet API-Sendungen als Status (gesendet, zugestellt, gelesen) innerhalb von messages-Ereignissen, mit der Nachrichten-ID. Der Text selbst steht im Laufprotokoll der Automation, das im Tab „Runs“ 30 Tage aufbewahrt wird, und in Conversations für die von Ihnen gewählte Dauer.
Wie rotiere ich das Forward-Geheimnis?
Klicken Sie auf der Seite der Nummer auf „New secret“ oder rufen Sie set_inbound_mode mit rotate_secret auf true auf. Das neue Geheimnis wird einmal angezeigt und signiert ab dann alles, auch Wiederholungen älterer Zustellungen. Aktualisieren Sie Ihren Server also sofort.
Braucht eine Forward URL den GET-Handshake von Meta?
Nein. Nur ein direktes Ziel wird von Meta aufgerufen und muss hub.challenge zurückgeben. Eine Forward URL wird von easyCoexistence aufgerufen und empfängt nur signierte POSTs.
Kann eine Nummer gleichzeitig ein direktes Ziel und eine Forward URL haben?
Nein. Eine Forward URL funktioniert nur, solange die Nummer verwaltet ist, und das Speichern eines direkten Ziels macht die Nummer direkt. Forward URL und ihr Geheimnis bleiben erhalten, sodass ein Wechsel zurück zu verwaltet die Weiterleitung wieder aufnimmt.
Weiterlesen
Bereit für den Start?
Richten Sie WhatsApp Coexistence in wenigen Minuten statt Monaten ein. Die App funktioniert weiterhin auf dem Telefon.
Kostenlose Testphase startenVerifiziert am