WhatsApp-API-Webhooks lokal testen mit ngrok
Du willst eine neue WhatsApp-Integration bauen — einen Bot, eine CRM-Anbindung, einen Benachrichtigungs-Flow —, aber dein Server läuft auf localhost. TextMeFlow kann dorthin nichts senden: Webhooks sind ausgehende POST-Requests von unseren Servern an eine öffentlich erreichbare URL. Bis dein Code auf einem echten Server liegt, brauchst du einen Tunnel. Dieser Artikel zeigt, wie das mit ngrok geht, ohne dass du versehentlich einen halbfertigen Endpunkt in Produktion stehen lässt.
Warum du überhaupt lokal testen solltest
Du könntest warten, bis dein Endpunkt deployt ist, um zu sehen, ob die Payload stimmt, aber das ist langsam: Jede Änderung braucht ein neues Deployment, um zu sehen, ob dein JSON-Parsing, deine Signaturprüfung und deine Geschäftslogik zusammenspielen. Lokales Testen mit einem echten, live ausgelösten Webhook — statt mit einer von Hand gebastelten Test-Payload — fängt Fehler ab, die du sonst erst in Produktion siehst: abweichende Header, die genaue Form von from_name bei Gruppennachrichten oder eine Medien-Nachricht mit einem file-Feld, mit dem du nicht gerechnet hast.
Schritt 1: ngrok starten
Installiere ngrok (brew install ngrok oder Download von deren Website) und starte einen Tunnel auf den Port, auf dem dein lokaler Server läuft:
ngrok http 3000
Ngrok gibt dir eine öffentliche URL wie https://a1b2c3d4.ngrok-free.app, die auf http://localhost:3000 weiterleitet. Im Gratis-Tarif ändert sich diese URL bei jedem Neustart — behalte das im Hinterkopf, wenn du den nächsten Schritt mehrmals wiederholst.
Schritt 2: den Webhook vorübergehend konfigurieren
Öffne /admin/webhook und trage die ngrok-URL als Endpunkt ein, zum Beispiel https://a1b2c3d4.ngrok-free.app/webhooks/whatsapp. Sobald du speicherst, siehst du das Webhook-Secret — kopiere es sofort, denn danach wird es maskiert. Schick dir selbst eine WhatsApp-Testnachricht an deine gekoppelte Nummer und prüfe, ob die Anfrage auf deinem lokalen Server ankommt.
Behandle diese ngrok-Konfiguration als Wegwerfarbeit: Sobald du mit dem Testen fertig bist, stelle den Endpunkt wieder auf deine echte Produktions-URL zurück. Ein vergessener ngrok-Tunnel, den es nach einem Laptop-Neustart nicht mehr gibt, ist der schnellste Weg, stillschweigend alle eingehenden Nachrichten zu verlieren.
Schritt 3: die Signatur prüfen, auch lokal
Es ist verlockend, die HMAC-Prüfung zu überspringen, „weil es ja nur ein lokaler Test ist“ — aber dann testest du nicht, was in Produktion wirklich passiert. Lies den Roh-Body, bevor irgendeine JSON-Middleware drankommt, und prüfe X-TextMeFlow-Signature sofort:
const crypto = require('crypto');
const express = require('express');
const app = express();
app.post('/webhooks/whatsapp', express.raw({ type: 'application/json' }), (req, res) => {
const expected = 'sha256=' + crypto
.createHmac('sha256', process.env.TMF_WEBHOOK_SECRET)
.update(req.body)
.digest('hex');
if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(req.headers['x-textmeflow-signature'] || ''))) {
return res.sendStatus(401);
}
const payload = JSON.parse(req.body);
console.log(payload);
res.sendStatus(200);
});
app.listen(3000);
Mehr Details zu den Headern, zur Retry-Logik und zum sichersten Weg, die Signatur zu vergleichen, findest du im Artikel über Webhook-Signaturen.
Schritt 4: den ngrok-Inspector zum Wiederholen nutzen
Die lokale Weboberfläche von ngrok unter http://127.0.0.1:4040 protokolliert jede eingehende Anfrage, inklusive Headern und Body. Das ist praktisch für zwei Dinge, ohne jedes Mal eine neue WhatsApp-Nachricht senden zu müssen:
- Die genaue Payload ansehen, die TextMeFlow gesendet hat, um deinen Parsing-Code darauf zu schreiben.
- Dieselbe Anfrage erneut abspielen („Replay“), nachdem du einen Bugfix auf deinem lokalen Server eingespielt hast, ohne noch einmal eine Nachricht schicken zu müssen.
Beachte aber: Ein Replay über den ngrok-Inspector verwendet dieselbe X-TextMeFlow-Event-Id. Wenn deine Idempotenz-Logik auf diesem Feld basiert — was wir empfehlen —, ignoriert dein eigener Code das Replay also zu Recht. Das ist kein Bug, das ist deine Deduplizierung, die funktioniert.
Häufige Fehler
Der Webhook bleibt auf „pending“ oder schlägt immer wieder fehl: Prüfe, ob dein Endpunkt innerhalb von 10 Sekunden ein 2xx zurückgibt. Aufwendige Verarbeitung (ein CRM aktualisieren, eine externe API aufrufen) führst du nach dieser Antwort aus, nicht davor — sonst wirkt dein lokaler Server wie ein Timeout, und du bekommst unnötige Wiederholungen mit einem Backoff von 1 Min., 5 Min., 30 Min., 2 Std. und 6 Std.
Ein zweiter klassischer Fehler: Die ngrok-URL wechselt bei jedem Neustart (Gratis-Tarif), das Webhook-Secret bleibt aber gleich, solange du den Endpunkt nicht neu anlegst. Wenn du die URL in /admin/webhook aktualisierst, deine lokale .env aber noch das alte Secret enthält, bekommst du überall 401 — selten „ein Angriff“, meist einfach ein nicht synchronisiertes Secret.
Bereit für den Livegang
Sobald dein Endpunkt lokal korrekt signiert, parst und innerhalb von 10 Sekunden antwortet, musst du nur noch die URL in /admin/webhook durch deine Produktionsadresse ersetzen. Die gesamte TextMeFlow-Infrastruktur läuft in der EU (Paris), sodass auch dein Test- und Produktionsverkehr in der EU bleibt. Noch kein Konto? Der Gratis-Tarif gibt dir 50 Nachrichten pro Monat, für immer — genug, um diesen ganzen Ablauf Ende-zu-Ende zu testen. Starte kostenlos.
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