· 5 min · TextMeFlow Team

WhatsApp-Webhook-Signaturen verifizieren (HMAC)

Jede eingehende WhatsApp-Antwort deines Kunden wird als Webhook an deinen Server gepusht. Das ist praktisch — kein Polling, nahezu sofortige Zustellung —, bedeutet aber auch: Dein Endpunkt ist eine öffentliche URL, an die jeder im Internet ein POST schicken kann. Wenn du nicht prüfst, ob die Anfrage wirklich von TextMeFlow stammt, kann ein Angreifer (oder einfach ein neugieriger Bot) gefälschte „Kundenantworten“ direkt in dein System einspeisen. So machst du es richtig — samt der zwei Fehler, die Signaturprüfungen im Produktivbetrieb unbemerkt kaputt machen.

Wie TextMeFlow Webhooks signiert

Jede Zustellung enthält einen X-TextMeFlow-Signature-Header in der Form sha256=<hex>, also einen HMAC-SHA256-Digest des rohen Request-Bodys, berechnet mit dem Webhook-Secret, das du beim Einrichten deines Endpunkts unter /admin/webhook erhalten hast. Das Secret ist ein 64-stelliger String, der nur einmal bei der Erstellung angezeigt wird — kopiere ihn sofort, danach wird er maskiert.

Neben der Signatur sind zwei weitere Header wichtig:

  • X-TextMeFlow-Event-Id — eine UUID pro Nachricht. Wiederholungen verwenden dieselbe ID, sie ist also dein Idempotenzschlüssel.
  • X-TextMeFlow-Delivery — eine UUID pro Zustellversuch, nützlich zum Durchsuchen der Logs, wenn du eine bestimmte Wiederholung debuggst.

Fehler Nr. 1: Gegen den geparsten Body prüfen

Der häufigste Bug ist, den HMAC über json_encode($parsedBody) zu berechnen statt über die rohen Bytes, die TextMeFlow tatsächlich gesendet hat. JSON-Encoder garantieren keine byte-identische Ausgabe — Schlüsselreihenfolge, Leerraum und Gleitkomma-Formatierung können sich zwischen dem Signierten und dem von dir neu Serialisierten unterscheiden. Die Lösung ist immer dieselbe: den rohen Body lesen, bevor eine JSON-parsende Middleware ihn anfasst, und diesen hashen.

In Express heißt das, express.raw({ type: 'application/json' }) gezielt auf deine Webhook-Route zu legen — hat express.json() den Body vorher schon verbraucht, sind die rohen Bytes weg und du verifizierst gegen undefined. In Flask nimmst du request.get_data(), nicht request.json. In PHP liefert file_get_contents('php://input') den unveränderten Stream.

$raw = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $raw, $secret);
$received = $_SERVER['HTTP_X_TEXTMEFLOW_SIGNATURE'] ?? '';

if (! hash_equals($expected, $received)) {
    http_response_code(401);
    exit;
}

$body = json_decode($raw, true);

Fehler Nr. 2: Signaturen mit == vergleichen

Vergleiche berechnete und empfangene Signatur niemals mit einem einfachen String-Gleichheitsoperator. Ein naiver Vergleich mit == oder .equals() verrät Timing-Informationen — wie viele führende Bytes übereinstimmten, bevor der Vergleich abbrach —, was (theoretisch) für einen geduldigen Angreifer reicht, um Byte für Byte eine gültige Signatur zu rekonstruieren. Verwende stattdessen einen Vergleich in konstanter Zeit: hash_equals() in PHP, hmac.compare_digest() in Python, crypto.timingSafeEqual() in Node (nachdem du geprüft hast, dass die Längen übereinstimmen, da timingSafeEqual bei Puffern ungleicher Länge eine Exception wirft, statt false zurückzugeben).

import hmac, hashlib, os
from flask import Flask, request, abort

app = Flask(__name__)
SECRET = os.environ['TMF_WEBHOOK_SECRET'].encode()

@app.post('/textmeflow-inbound')
def inbound():
    raw = request.get_data()
    expected = 'sha256=' + hmac.new(SECRET, raw, hashlib.sha256).hexdigest()
    received = request.headers.get('X-TextMeFlow-Signature', '')
    if not hmac.compare_digest(expected, received):
        abort(401)
    body = request.get_json()
    # ...handle body...
    return '', 200

Wiederholungen ohne Doppelverarbeitung

Eine Zustellung gilt als erfolgreich, sobald innerhalb von 10 Sekunden eine 2xx-Antwort zurückkommt. Alles andere löst eine Wiederholung aus, bis zu 5 Mal mit Wartezeiten von 1m, 5m, 30m, 2h, 6h — das gilt für 408, 429, 5xx-Antworten und Netzwerk-Timeouts. Nach insgesamt 6 Versuchen (dem ursprünglichen plus 5 Wiederholungen) wird die Zustellung als fehlgeschlagen markiert, und den Status jedes Versuchs siehst du unter /admin/webhook. Jedes andere 4xx gilt als endgültiger Fehler ohne Wiederholung — ein 401 bedeutet fast immer, dass dein gespeichertes Secret nicht mehr zum konfigurierten passt; prüfe das also zuerst, bevor du einen Angriff vermutest.

Da Wiederholungen erwartetes Verhalten und kein Sonderfall sind, muss dein Endpunkt idempotent sein: Speichere X-TextMeFlow-Event-Id und überspringe die Verarbeitung, wenn du diese ID schon bearbeitet hast. Ein Unique-Constraint auf dieser Spalte in der Tabelle, in der du eingehende Nachrichten protokollierst, genügt — lass die Datenbank das doppelte Einfügen ablehnen, statt eine eigene Deduplizierungslogik zu bauen.

Eine weitere Folge des 10-Sekunden-Fensters: Erledige die eigentliche Arbeit (ein CRM aktualisieren, einen Buchungsflow anstoßen, eine langsame nachgelagerte API aufrufen) nachdem du 200 geantwortet hast, nicht davor. Erst bestätigen, dann asynchron verarbeiten — ein langsamer Handler, der länger als 10 Sekunden blockiert, sieht genauso aus wie ein Timeout und wird unnötig wiederholt.

Umstieg von TextMeBot

Wenn du von TextMeBot wechselst, ist die Payload-Struktur identisch (type, from, from_name, to, file, message) — dein Parsing-Code bleibt also unverändert. Hinzufügen musst du nur die Signaturprüfung selbst: TextMeBot signiert seine Webhooks nicht. Wenn deine alte Integration nie etwas verifiziert hat, ist jetzt der Moment, diese Lücke vor dem Produktivbetrieb zu schließen. Die vollständige Feldreferenz und die Header-Liste findest du in der Webhook-Dokumentation.

Du willst es live ausprobieren? Richte deinen Endpunkt nach der Anmeldung unter /admin/webhook ein — der kostenlose Tarif enthält 50 Nachrichten pro Monat, für immer, genug, um einen kompletten Webhook-Flow aufzusetzen und zu testen. Kostenlos starten.

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