WhatsApp-Webhook-Wiederholungen, Duplikate und Reihenfolge: So gehen Sie damit um
Meta wiederholt einen WhatsApp-Webhook, der etwas anderes als HTTP 200 zurückbekommt, zuerst sofort und dann in abnehmender Frequenz bis zu 7 Tage lang, danach verwirft Meta ihn. Die Wiederholungen gehen an jede App, die für das Konto abonniert ist, daher sind Duplikate normal. Antworten Sie schnell mit 200, deduplizieren Sie über die Nachrichten-ID oder über Status-ID plus Status, und sortieren Sie Ereignisse nach ihren eigenen Zeitstempeln.
easyCoexistence verbindet Ihre WhatsApp-Business-App-Nummer über Coexistence mit der Cloud API von Meta und fängt Metas erneute Zustellungen ab, bevor Ihre Automatisierungen sie sehen, sodass eine wiederholte Nachricht keine zweite KI-Antwort auslöst.
Wie lange Meta einen Webhook wiederholt, der kein HTTP 200 erhalten hat, bevor es ihn verwirft.
Die meisten Updates bündelt Meta in einem einzigen POST; Batching ist nicht garantiert, daher behandeln Sie jede Anfrage einzeln.
Größte Payload, die ein WhatsApp-Webhook-POST enthalten kann.
Wie lange easyCoexistence jede eingehende Nachrichten-ID speichert, damit eine erneut zugestellte Nachricht keine Automatisierung zweimal auslöst.
Versuche pro Weiterleitung an Ihre Forward URL, jeweils 10 Sekunden auf eine 2xx-Antwort wartend, über etwa 33 Stunden.
Wann wiederholt Meta einen WhatsApp-Webhook?
Immer dann, wenn eine Zustellung an Ihren Endpoint einen anderen HTTP-Statuscode als 200 erhält oder gar nicht zugestellt werden kann. Meta wiederholt sofort, dann noch einige Male in abnehmender Frequenz über die nächsten 7 Tage und verwirft danach alles, was noch nicht bestätigt ist. Die Wiederholungen gehen an jede App, die für dieses Feld des WhatsApp Business Account abonniert ist, weshalb Meta vor doppelten Benachrichtigungen warnt. Es gibt keine API, um vergangene Webhooks abzurufen, daher ist eine Zustellung, deren 7 Tage abgelaufen sind, für Ihr System verloren.
Warum kommen Duplikate an, auch wenn Ihr Server gesund ist?
Weil eine Zustellung auf Ihrer Seite erfolgreich sein kann und dennoch für Meta als fehlgeschlagen erscheint. Ein Handler, der Arbeit erledigt, bevor er antwortet, kann Metas Wartezeit überschreiten, sodass Meta etwas wiederholt, das Sie bereits verarbeitet haben. Ein Deployment, das den Server mitten in einer Anfrage neu startet, ein Load Balancer, der kurzzeitig 502 zurückgibt, oder eine 201 oder 204 statt 200 gelten alle als Fehler. Batches fügen einen weiteren Fall hinzu: Ein einzelner POST kann viele Updates enthalten, daher bringt ein Timeout bei einem großen Batch den gesamten Batch zurück, einschließlich der Updates, die Sie bereits bearbeitet haben.
Nach welchem Schlüssel sollten Sie deduplizieren?
Nach Metas eigenen IDs, je nach Ereignistyp gewählt, weil eine Nachricht legitim mehrere Webhooks erzeugt. Ein Statusschlüssel ohne den Statuswert würde delivered und read als Kopien von sent verwerfen, und ein Anrufschlüssel ohne das Ereignis würde nur die erste Phase eines Anrufs behalten. Speichern Sie die Schlüssel mit einem eindeutigen Index, damit zwei Worker, die dieselbe Wiederholung bearbeiten, nicht beide gewinnen können:
In welcher Reihenfolge kommen Webhooks an?
Nicht unbedingt in der Reihenfolge, in der die Dinge passiert sind. Meta gibt in seiner Dokumentation kein Versprechen zur Reihenfolge ab, eine wiederholte Zustellung landet nach neueren, und ein Status kann einen Schritt überspringen: Meta sendet read ohne delivered, wenn eine Nachricht im Moment ihres Eingangs gelesen wird. Speichern Sie Ereignisse daher mit ihrem eigenen Zeitstempelfeld, vergleichen Sie einen Status nach Rang statt nach Eingangszeit, und lassen Sie eine spätere Kundennachricht eine verspätet eingetroffene frühere überschreiben. Bei einer Coexistence-Nummer kann der einmalige Verlaufsimport rund um das Onboarding mit Live-Nachrichten überlappen, und die Nachrichten-ID gleicht beides ab.
Wie sieht ein sicherer Handler aus?
Vier Schritte: prüfen, genau 200 antworten, deduplizieren und dann aus einer Queue arbeiten, damit zwischen der Anfrage von Meta und Ihrer Antwort nichts Langsames liegt. Diese Version prüft X-Hub-Signature-256 mit dem Secret Ihrer eigenen Meta-App. Bei einer Nummer, die über easyCoexistence verbunden ist, signiert Meta mit dem App-Secret von easyCoexistence. Ein direktes Ziel authentifiziert sich daher stattdessen über ein langes Secret im URL-Pfad, oder Sie wechseln zur verwalteten Weiterleitung, die pro Nummer signiert wird.
// meta-webhook.mjs: node meta-webhook.mjs (no dependencies)
import crypto from "node:crypto";
import http from "node:http";
const APP_SECRET = process.env.META_APP_SECRET; // the secret of the Meta app that subscribed
const seen = new Set(); // keys already accepted: a unique index in a database in production
// One key per thing that happened, so a redelivery maps to the same keys.
function keysOf(field, value) {
const keys = [];
for (const m of value.messages ?? []) keys.push(`${field}:msg:${m.id}`);
for (const s of value.statuses ?? []) keys.push(`${field}:status:${s.id}:${s.status}`);
for (const e of value.message_echoes ?? []) keys.push(`${field}:echo:${e.id}`);
for (const c of value.calls ?? []) keys.push(`${field}:call:${c.id}:${c.event}`);
return keys;
}
http.createServer((req, res) => {
const chunks = [];
req.on("data", (c) => chunks.push(c));
req.on("end", () => {
const raw = Buffer.concat(chunks);
const got = Buffer.from(String(req.headers["x-hub-signature-256"] ?? ""));
const want = Buffer.from("sha256=" + crypto.createHmac("sha256", APP_SECRET).update(raw).digest("hex"));
if (req.method !== "POST" || got.length !== want.length || !crypto.timingSafeEqual(got, want)) {
res.writeHead(401).end();
return;
}
res.writeHead(200).end(); // exactly 200, before any work
const body = JSON.parse(raw.toString("utf8"));
for (const entry of body.entry ?? []) {
for (const change of entry.changes ?? []) {
for (const key of keysOf(change.field, change.value ?? {})) {
if (seen.has(key)) continue; // a retry of something already accepted
seen.add(key);
// queue { key, field: change.field, value: change.value } for a worker here
console.log("new", key);
}
}
}
});
}).listen(process.env.PORT ?? 3000);Wie geht easyCoexistence mit Wiederholungen bei einer verbundenen Nummer um?
Eingehend prüft easyCoexistence die Signatur von Meta, antwortet mit 200 und führt Automatisierungen nach der Antwort aus, sodass Meta nicht wiederholt, weil eine KI-Antwort ein paar Sekunden gedauert hat. Jede eingehende Nachrichten-ID wird 7 Tage lang gespeichert, der Länge des Wiederholungsfensters von Meta, und eine erneut zugestellte Nachricht wird erkannt und löst keine zweite automatische Antwort aus.
Ausgehend an Ihre Forward URL wird jede Änderung von Meta zu einer Zustellung mit einer ID in X-EC-Delivery, die über Weiterleitungswiederholungen gleich bleibt: 7 Versuche über etwa 33 Stunden, jeweils 10 Sekunden auf eine 2xx-Antwort wartend. Eine Änderung, die Meta selbst erneut zustellt, wird unter einer neuen Delivery-ID weitergeleitet. Deduplizieren Sie daher zusätzlich über Metas IDs innerhalb von value.
Häufige Fehler
- Status-Webhooks nur über die ID deduplizieren. sent, delivered und read teilen sich die wamid, daher braucht der Schlüssel auch den Status.
- Verarbeitung vor der Antwort. Ein langsamer Handler lässt Meta Arbeit wiederholen, die Sie bereits erledigt haben; antworten Sie zuerst mit 200 und arbeiten Sie dann aus einer Queue.
- 201 oder 204 zurückgeben. Metas Dokumentation behandelt jeden anderen Status als 200 als fehlgeschlagene Zustellung und wiederholt sie.
- Weiterleitungen nur über X-EC-Delivery deduplizieren. Eine Änderung, die Meta erneut zustellt, kommt unter einer neuen Delivery-ID an; behalten Sie Metas IDs als zweiten Schlüssel.
Weiterleitungen an Ihren Server sind signiert, in Warteschlange gestellt und werden wiederholt, und jede Nummer wird rund um die Uhr überwacht. Von US$ 9 bis US$ 0.75 pro Nummer und Monat, sinkend mit jeder weiteren Nummer. Die ersten 3 Tage sind kostenlos.
Häufig gestellte Fragen
Wie lange sollten Sie die IDs aufbewahren, die Sie bereits gesehen haben?
Mindestens 7 Tage, dem Wiederholungsfenster von Meta. Eine Zustellung, die Meta am sechsten Tag wiederholt, muss noch zu ihrem Schlüssel passen, sonst wird sie als neu verarbeitet.
Was passiert mit den Nachrichten Ihrer Kunden, wenn Ihr Endpoint tagelang ausfällt?
Meta wiederholt bis zu 7 Tage lang und verwirft die Webhooks dann. Bei einer Coexistence-Nummer liegen die Unterhaltungen weiterhin in der WhatsApp-Business-App auf dem Telefon, sodass das Unternehmen von dort antworten kann.
Können Sie verpasste Webhooks erneut abspielen?
Nicht über Meta: Es gibt keine API für historische Webhook-Daten. Der einmalige Verlaufsimport einer Coexistence-Nummer läuft nur beim Onboarding und kann für dieselbe Verbindung nicht erneut angefordert werden.
Sendet Meta dasselbe Update an mehr als einen Server?
Es sendet an jede App, die für das WhatsApp Business Account zu diesem Feld abonniert ist. Mit einem Destination Override gehen die Nachrichtenfelder der Nummer an die Override-URL statt an den Standard-Callback dieser App.
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