So empfangen Sie die WhatsApp-Nachrichten und Social-Kommentare Ihrer Kunden per Webhook
Jede Verbindung erhält über die Partner API von easyCoexistence einen eigenen Webhook für die WhatsApp-Nachrichten oder Social-Kommentare Ihrer Kunden. WhatsApp-Nachrichten gehen direkt von Meta an diese URL und sind mit dem Secret der Tech-Provider-App signiert, nicht mit einem Secret, das Sie besitzen. Daher authentifiziert ein langes, zufälliges Geheimnis im URL-Pfad sie. Instagram- und Facebook-Kommentare und DMs sowie TikTok-Kommentare werden bei Eingang weitergeleitet und pro Konto mit X-EC-Signature signiert.
Die maximale Länge der alternativen Callback-URL von Meta, über die die Nachrichten einer Nummer an Ihren Endpoint gesendet werden.
Wie lange Meta einen WhatsApp-Webhook wiederholt, den Ihr Endpoint nicht angenommen hat, mit abnehmender Häufigkeit, was zu Duplikaten führen kann.
Das Netz von Meta; whois-Routenabfragen dafür listen die Adressen auf, von denen WhatsApp-Webhooks kommen, die Meta regelmäßig ändert.
Die maximale Größe einer WhatsApp-Webhook-Payload laut Meta.
Das Alter, nach dem ein signierter Zeitstempel eines weitergeleiteten Events abgelehnt werden sollte, wobei der HMAC in konstanter Zeit verglichen wird.
Wie bekommt jede Verbindung ein eigenes Ziel?
Über je einen Aufruf pro Ressource. Eine WhatsApp-Nummer nutzt PUT /connections/{id}/webhook mit einer url und einem verify_token, oder dasselbe Paar als webhook_url und webhook_verify_token in ihrer Connect-Session, sodass die Nummer ab der ersten Minute an Sie geleitet wird. Ein Social-Konto nutzt PUT /channels/{id}/webhook, sobald es verbunden ist. Eine url von null schaltet die Zustellung bei beiden ab. Die beiden Wege unterscheiden sich darin, wer zustellt und wie Sie authentifizieren:
| WhatsApp number | Instagram, Facebook, TikTok | |
|---|---|---|
| Set with | webhook_url on the session, or PUT /connections/{id}/webhook | PUT /channels/{id}/webhook, after it connects |
| Delivered by | Meta, straight to your URL | easyCoexistence, forwarding each event as it arrives |
| Body | Meta's webhook, unchanged | platform, account_id, external_id and the network's entry |
| Authenticate | A long random secret in the URL path | X-EC-Signature, keyed with the account's secret |
| Retries | Meta's own, for up to 7 days | None: one attempt |
| Copy kept | None | None |
Wie leiten Sie die Nachrichten einer Nummer an Ihren Endpoint?
Geben Sie eine HTTPS-URL an, deren Pfad ein langes, zufälliges Geheimnis enthält, dazu ein Verify-Token: webhook_verify_token in einer Connect-Session, 8 bis 200 Zeichen, oder verify_token beim PUT. Meta prüft die URL sofort mit einem GET, das hub.mode=subscribe, hub.verify_token und hub.challenge enthält. Ihr Endpoint muss bei passendem Token mit dem Wert von hub.challenge antworten. Schlägt dieser Handshake fehl, gibt der PUT 502 meta_rejected mit der eigenen Meldung von Meta zurück. Bei einer Connect-Session verbindet sich die Nummer trotzdem, und das last_error der Session erklärt, warum die URL nicht übernommen wurde.
import express from "express";
import { timingSafeEqual } from "node:crypto";
const PATH_SECRET = process.env.WA_PATH_SECRET; // the random part of webhook_url
const VERIFY_TOKEN = process.env.WA_VERIFY_TOKEN; // the verify token you sent
const app = express();
function same(a, b) {
const x = Buffer.from(String(a)), y = Buffer.from(String(b));
return x.length === y.length && timingSafeEqual(x, y);
}
// Meta's handshake, run when the destination is set
app.get("/wa/:secret", (req, res) => {
if (!same(req.params.secret, PATH_SECRET)) return res.sendStatus(404);
if (req.query["hub.mode"] !== "subscribe" || !same(req.query["hub.verify_token"], VERIFY_TOKEN)) {
return res.sendStatus(403);
}
res.send(req.query["hub.challenge"]);
});
// Messages, echoes and the one-time import; payloads reach 3 MB
app.post("/wa/:secret", express.json({ limit: "4mb" }), (req, res) => {
if (!same(req.params.secret, PATH_SECRET)) return res.sendStatus(404);
res.sendStatus(200); // answer first: Meta retries for up to 7 days
enqueue(req.body); // deduplicate on each message id before acting
});Warum können Sie Metas Signatur nicht prüfen, und was ersetzt sie?
Meta signiert jede Zustellung mit X-Hub-Signature-256, einem HMAC-SHA256 über die Payload, berechnet mit dem App Secret der empfangenden App. Bei den Nummern Ihrer Kunden ist diese App die Tech-Provider-App von easyCoexistence, und ihr Secret wird nie geteilt, sodass der Header auf Ihrer Seite nicht verifiziert werden kann. Stattdessen dient das lange, zufällige Geheimnis im URL-Pfad als Berechtigungsnachweis: Vergleichen Sie es in konstanter Zeit und lehnen Sie alles andere ab. Als zweite Schicht legen Sie eine Allowlist mit den Routen an, die Meta unter AS32934 registriert hat, und aktualisieren Sie diese, da Meta seine IP-Adressen regelmäßig ändert.
Welche WhatsApp-Webhooks erreichen Ihre URL?
Die Felder, die eine alternative Callback-URL von Meta übertragen kann: messages für das, was Kunden senden, und den Status dessen, was Sie senden; smb_message_echoes für das, was das Unternehmen über die WhatsApp-Business-App sendet; sowie der einmalige Import mit history und smb_app_state_sync. Template-Webhooks und Konto-Webhooks wie account_update sendet Meta nie an ein Override. Sie gehen stattdessen an den Callback von easyCoexistence, weshalb die Prüfung der Templates per Polling gelesen wird und eine verworfene Nachricht Sie als Status-Event erreicht.
- Das Ziel wird am WhatsApp Business Account gesetzt, sodass zwei Nummern in einem Konto es teilen: Routen Sie anhand von value.metadata.
phone_number_id. - Medien kommen als ID an; laden Sie die Datei mit dem Token des Kunden aus dem Credentials-Aufruf von Meta.
- Payloads können 3 MB erreichen; erhöhen Sie jedes darunter gesetzte Limit für die Body-Größe.
Wie sieht ein weitergeleitetes Social-Event aus?
Ein POST mit Content-Type application/json und einem X-EC-Signature-Header, der vier Schlüssel enthält: platform; account_id, die Kanal-ID, die die Partner API verwendet; external_id, die ID des Kontos im Netzwerk; und entry. Bei Instagram und Facebook ist entry der unveränderte Webhook-Entry von Meta, mit changes für Kommentare und Erwähnungen und messaging für DMs. Bei TikTok enthält er das Ereignis comment.update mit geparstem content sowie comment_id, video_id und parent_comment_id als Strings, damit 64-Bit-IDs nicht gerundet werden.
- Instagram-Konten sind auf comments, messages und mentions abonniert, Facebook-Seiten auf feed, messages und mention; TikTok sendet comment.update.
- easyCoexistence erhält keine Kommentar-Events von YouTube oder LinkedIn: deren PUT antwortet mit 400
not_supported, und deren Kommentare lesen Sie über die API des jeweiligen Netzwerks mit den Zugangsdaten. - Weiterleitungen enthalten keinen X-EC-Event- oder X-EC-Delivery-Header; filtern Sie Duplikate daher anhand der IDs des Netzwerks, etwa einer Kommentar-ID oder einer message-mid.
{
"platform": "instagram",
"account_id": "<CHANNEL_ID>",
"external_id": "<INSTAGRAM_ACCOUNT_ID>",
"entry": {
"id": "<INSTAGRAM_ACCOUNT_ID>",
"time": 1793440800,
"changes": [
{
"field": "comments",
"value": {
"id": "<COMMENT_ID>",
"from": { "id": "<INSTAGRAM_SCOPED_ID>", "username": "<USERNAME>" },
"text": "<COMMENT_TEXT>",
"media": { "id": "<MEDIA_ID>", "media_product_type": "<MEDIA_PRODUCT_TYPE>" }
}
}
]
}
}Wie prüfen Sie X-EC-Signature Schritt für Schritt?
Mit dem signing_secret, das PUT /channels/{id}/webhook zurückgegeben hat; es wird nur einmal angezeigt und ist für dieses Konto eindeutig. Der Header lautet t=<unix>,v1=<hex>. Dann gilt für jede Zustellung:
- Lesen Sie den rohen Body der Anfrage als Bytes, bevor Sie irgendein JSON parsen.
- Teilen Sie den Header an den Kommas in t, eine Unix-Zeit in Sekunden, und v1, einen Hex-Digest.
- Lehnen Sie die Zustellung ab, wenn t mehr als 5 Minuten von Ihrer Uhr entfernt ist.
- Berechnen Sie HMAC-SHA256 über t, einen Punkt und den rohen Body, geschlüsselt mit dem Secret dieses Kontos, als Hex.
- Vergleichen Sie das Ergebnis mit v1 in konstanter Zeit, antworten Sie dann mit 2xx und stellen Sie die Arbeit in die Warteschlange.
import express from "express";
import { createHmac, timingSafeEqual } from "node:crypto";
const app = express();
const secrets = new Map(); // channel id -> signing_secret, kept in your database
app.post("/hooks/social", express.raw({ type: "application/json" }), (req, res) => {
const sig = Object.fromEntries(
(req.get("X-EC-Signature") ?? "").split(",").map((part) => part.split("=", 2)),
);
if (!/^\d+$/.test(sig.t ?? "") || Math.abs(Date.now() / 1000 - Number(sig.t)) > 300) {
return res.sendStatus(401); // missing or stale timestamp
}
let event;
try {
event = JSON.parse(req.body.toString("utf8")); // platform, account_id, external_id, entry
} catch {
return res.sendStatus(400);
}
const secret = secrets.get(event.account_id);
if (!secret || !sig.v1) return res.sendStatus(401);
const expected = createHmac("sha256", secret)
.update(sig.t + ".")
.update(req.body) // the raw bytes, exactly as they arrived
.digest("hex");
if (expected.length !== sig.v1.length ||
!timingSafeEqual(Buffer.from(expected), Buffer.from(sig.v1))) {
return res.sendStatus(401);
}
res.sendStatus(204); // one attempt and no retries: acknowledge, then work
enqueue(event);
});Was passiert, wenn kein Ziel gesetzt ist?
Nichts erreicht Sie, und nichts wartet darauf, später gesendet zu werden. Eine Nummer ohne webhook_url fällt auf den Callback von easyCoexistence zurück, wo ihre Nachrichten ohne Speicherung verworfen werden. Sie erhält auch keinen Import des Chatverlaufs, der erst angefordert wird, sobald ein Ziel existiert. Ein Social-Konto ohne Ziel wird nicht weitergeleitet: Seine Events erreichen zwar die App von easyCoexistence, aber keines wird für Sie zurückgehalten. Setzen Sie jedes Ziel, bevor Sie den Datenverkehr benötigen.
Was passiert mit einem Ziel, wenn eine Verbindung abbricht oder entfernt wird?
Eine Nummer behält ihr Ziel gespeichert. Wenn sich eine abgebrochene Nummer neu verbindet, setzt easyCoexistence Ihre URL bei Meta erneut, und dasselbe geschieht, wenn eine pausierte Nummer zurückkehrt. Entfernen Sie ein Social-Konto, werden sein Ziel und sein Secret gelöscht. Rufen Sie PUT /channels/{id}/webhook nach der erneuten Verbindung daher erneut auf und speichern Sie das neue Secret. Dieser PUT stellt bei jedem Aufruf mit einer URL ein neues Secret aus, und das alte signiert sofort nicht mehr.
So richten Sie es ein
- Put a secret in the URLChoose an HTTPS URL whose path holds a long random string, 200 characters or fewer in all, and make its GET answer Meta's hub.challenge.
- Route the number's messagesSend webhook_url and webhook_verify_token on the connect session, or PUT /connections/{id}/webhook once the number is connected.
- Turn on each social accountCall PUT /channels/{id}/webhook with your URL and store the signing_secret it returns against that channel.
- Verify, then acknowledgeCheck the path secret on WhatsApp deliveries and X-EC-Signature on forwarded ones, answer 2xx at once, then process from a queue.
Häufige Fehler
- X-Hub-Signature-256 bei WhatsApp-Zustellungen Ihrer Kunden prüfen. Meta berechnet sie mit dem App Secret von easyCoexistence, das nie geteilt wird, daher kann die Prüfung nie gelingen. Authentifizieren Sie stattdessen mit dem Geheimnis im URL-Pfad.
- X-EC-Signature über geparstes JSON prüfen. Der HMAC umfasst den rohen Body Byte für Byte, und ein erneutes Serialisieren verändert die Bytes. Prüfen Sie daher vor dem Parsen.
- Ein Secret für alle Kanäle verwenden. Jedes Social-Konto signiert mit seinem eigenen Secret, Status-Events mit einem anderen. Suchen Sie das Secret daher anhand der account_id.
- Langsame Arbeit ausführen, bevor Sie ein weitergeleitetes Event beantworten. Es wird einmal gesendet, wartet 8 Sekunden auf Ihre Antwort und wird nie wiederholt. Antworten Sie daher zuerst mit 2xx und verarbeiten Sie danach.
easyCoexistence leitet die Nachrichten jeder Kundennummer direkt von Meta an Ihren Server weiter und gibt Instagram- und Facebook-Kommentare und DMs sowie TikTok-Kommentare bei Eingang an Ihren Endpoint weiter, pro Konto signiert, ohne gespeicherte Kopie und mit Überwachung jeder Verbindung rund um die Uhr. US$ 9 bis US$ 0.75 pro Verbindung und Monat, sinkend mit jeder weiteren Verbindung, mit den ersten 3 Tagen als kostenlose Testphase.
Häufig gestellte Fragen
Kann ich Metas Signatur auf den WhatsApp-Nachrichten meiner Kunden prüfen?
Nein. Meta signiert sie mit dem Secret der Tech-Provider-App von easyCoexistence, das nie geteilt wird. Authentifizieren Sie mit dem langen, zufälligen Geheimnis in Ihrem URL-Pfad und optional mit den IP-Bereichen von Meta.
Leiten YouTube- und LinkedIn-Verbindungen Kommentar-Events weiter?
Nein. easyCoexistence erhält von keinem der beiden Kommentar-Events, daher antwortet PUT /channels/{id}/webhook mit 400 not_supported. Lesen Sie deren Kommentare über die API des jeweiligen Netzwerks mit den Zugangsdaten des Kanals.
Werden weitergeleitete Social-Events erneut gesendet, wenn mein Server ausfällt?
Nein. Jedes wird einmal gesendet, und es wird keine Kopie gespeichert. WhatsApp-Zustellungen unterscheiden sich, weil Meta selbst sie bis zu 7 Tage lang wiederholt.
Gehen Nachrichten über easyCoexistence?
Bei WhatsApp nicht: Meta stellt die Nachrichten einer Nummer direkt an den Webhook zu, den Sie gesetzt haben. Kommentare und DMs aus den Social-Netzwerken werden bei Eingang an Ihren Endpoint weitergeleitet, pro Konto signiert und ohne gespeicherte Kopie.
Weiterlesen
Verbinden Sie Ihren ersten Kanal in zwei Minuten.
Keine Plattform-Prüfungen, auf die Sie warten müssen. Verbinden Sie WhatsApp, Instagram, TikTok oder einen anderen Kanal, bitten Sie dann Ihre KI, zu posten, zu antworten oder Berichte zu erstellen, und sehen Sie ihr bei der Arbeit zu.
- 3 Tage kostenlos
- Jederzeit kündbar
- Nur offizielle APIs
- Überwacht rund um die Uhr (24/7)
Verifiziert am