WhatsApp-Webhook: Retries und Idempotenz mit der Event-Id
Wenn du eingehende WhatsApp-Nachrichten über einen textmeflow-Webhook empfängst, sieht dein Endpunkt früher oder später dasselbe Ereignis mehr als einmal. Das ist kein Bug – so funktioniert zuverlässige Webhook-Zustellung nun mal. Berücksichtigt dein Endpunkt das nicht, versendest du eine Antwort doppelt, buchst eine Bestellung doppelt ab oder legst doppelte Support-Tickets an. Dieser Artikel behandelt die Retry-Richtlinie und den einen Header, der all das löst: X-TextMeFlow-Event-Id.
Warum es überhaupt Retries gibt
Eine Webhook-Zustellung ist ein POST-Request über das öffentliche Internet an einen Server, den du betreibst. Zwischen textmeflow und deinem Endpunkt liegen DNS, TLS, dein Load Balancer, der Middleware-Stack deines Frameworks und dein Anwendungscode – und jedes davon kann ein paar Sekunden ausfallen oder in ein Timeout laufen, ohne dass mit deiner Integration etwas nicht stimmt. Würde textmeflow nach dem ersten Versuch aufgeben, bedeutete ein Aussetzer auf deiner Seite eine verlorene WhatsApp-Nachricht. Deshalb wird es erneut versucht.
Die praktische Folge: Dein Endpunkt muss davon ausgehen, dass er dieselbe Webhook-Zustellung mehr als einmal erhalten kann, und darf das nicht als Fehler behandeln.
Der Retry-Plan
Jeder Zustellversuch wird allein anhand der HTTP-Antwort bewertet:
- 2xx innerhalb von 10 Sekunden – zugestellt, kein Retry.
- 408, 429, 5xx oder ein Timeout/Netzwerkfehler – wiederholbar. textmeflow versucht es bis zu 5-mal mit Backoff
1m, 5m, 30m, 2h, 6h, also insgesamt bis zu 6 Versuchen (der ursprüngliche plus 5 Retries), verteilt über etwa 8–9 Stunden. - Jeder andere 4xx – gilt als fehlgeschlagen, kein Retry. Ein
401bedeutet fast immer, dass dein HMAC-Secret nicht mehr zu dem passt, was konfiguriert ist – behebe das auf deiner Seite, statt zu erwarten, dass ein Retry hilft.
Nach dem 6. Versuch wird die Zustellung als failed markiert, und du kannst das Ergebnis jedes Versuchs unter /admin/webhook einsehen. Antworte schnell und mit einem 2xx, sobald du das Ereignis dauerhaft in eine Warteschlange gestellt hast – führe keine langsame Verarbeitung (API-Aufrufe, aufwendige Datenbankschreibvorgänge) im Request-Handler selbst durch, denn ein langsames 2xx, das das 10-Sekunden-Fenster verpasst, zählt trotzdem als Timeout.
Der Header, der Retries sicher macht
Jede Webhook-Payload trägt zwei verschiedene Kennungen, und sie zu verwechseln ist der häufigste Fehler:
X-TextMeFlow-Event-Id– eine UUID, die die Nachricht identifiziert. Sie bleibt bei jedem Retry derselben Zustellung identisch.X-TextMeFlow-Delivery– eine UUID, die den Zustellversuch identifiziert. Sie ist bei jedem Retry anders, was für die Log-Suche pro Versuch nützlich, für die Deduplizierung aber unbrauchbar ist.
Um deinen Endpunkt idempotent zu machen, speichere X-TextMeFlow-Event-Id als Primärschlüssel (oder als Spalte mit eindeutigem Index) überall dort, wo du eingehende Nachrichten ablegst, und prüfe sie, bevor du auf eine neue Nachricht reagierst:
$eventId = $request->header('X-TextMeFlow-Event-Id');
if (InboundMessage::where('event_id', $eventId)->exists()) {
return response('', 200); // bereits verarbeitet, bestätigen und abbrechen
}
InboundMessage::create([
'event_id' => $eventId,
'payload' => $request->getContent(),
]);
// ...die eigentliche Verarbeitung in die Warteschlange stellen, dann 2xx zurückgeben
return response('', 200);
Dasselbe Muster funktioniert in jeder Sprache: eine Eindeutigkeitsbedingung auf der Event-Id plus ein frühes Return. Kein verteilter Lock, kein Deduplizierungsfenster, das du abstimmen musst – die Id bleibt über die gesamte Lebensdauer dieser Zustellung stabil, eine einfache Eindeutigkeitsprüfung genügt also.
Kombiniere es mit der Signaturprüfung
Idempotenz und Signaturprüfung lösen unterschiedliche Probleme, und du brauchst beides. Die Prüfung von X-TextMeFlow-Signature (HMAC-SHA256 über den rohen Body, mit konstanter Zeit verglichen) bestätigt, dass die Anfrage wirklich von textmeflow stammt; die Prüfung von X-TextMeFlow-Event-Id bestätigt, dass du genau diese Nachricht noch nicht verarbeitet hast. Zur Signaturseite siehe WhatsApp-Webhook-Signaturen verifizieren, die vollständige Referenz zu Headern und Retries steht in der Webhook-Dokumentation.
Was das in der Praxis verhindert
- Ein Kunde, der dieselbe automatische Antwort zweimal bekommt, weil dein Handler sowohl beim ursprünglichen Versuch als auch bei einem durch eine langsame Antwort ausgelösten Retry lief.
- Ein Bestellstatus, der hin- und herspringt, wenn zwei Versuche gegeneinander laufen – dedupliziere anhand der Event-Id, bevor du einen veränderlichen Zustand anfasst.
- Lautes Alerting: Wenn dein Error-Tracker bei jedem wiederholbaren 5xx anschlägt, wirst du für genau die Fehler alarmiert, die der Retry-Plan von selbst abfangen soll.
Bring das einmal ganz oben in deinem Webhook-Handler in Ordnung, und jede Integration, die du darauf aufbaust – Bestellbestätigungen, Ticket-Erstellung im Support, CRM-Sync –, erbt die Sicherheit gratis.
Willst du das Retry-Verhalten selbst sehen? Erstelle ein kostenloses textmeflow-Konto, richte einen Webhook-Endpunkt ein und nutze den Test per Klick unter /admin/webhook, um die Header eintreffen zu sehen.
Selbst WhatsApp-Nachrichten per API senden?
Für immer gratis bis 50 Nachrichten/Monat. QR scannen und in 5 Minuten die erste Nachricht senden.
Für immer gratis