Mit dem lokalen Testen von Twilio-Webhooks empfängst du SMS-Antworten, Voice-Callbacks und Messaging-Status-Updates direkt auf deinem Rechner. Twilio sendet Webhooks als HTTP-POST-Requests mit formularkodierten Payloads – dein localhost braucht während der Entwicklung eine öffentliche HTTPS-URL, um sie zu empfangen.
Warum Twilio-Callbacks eine öffentliche URL brauchen
Wenn jemand eine SMS an deine Twilio-Nummer sendet oder einen Anruf abschließt, schickt Twilio die Eventdaten per POST an deine konfigurierte Webhook-URL. Lokale Adressen wie http://localhost:3000/sms sind von Twilios Infrastruktur nicht erreichbar. Ein Localhost-Tunnel überbrückt diese Lücke mit einem öffentlichen HTTPS-Endpunkt.
Twilio-Webhook-Typen zum lokalen Testen
- SMS eingehend: wenn ein Nutzer eine Textnachricht an deine Twilio-Nummer sendet.
- SMS-Status-Callbacks: Zustellbestätigungen (sent, delivered, failed).
- Voice-Callbacks: TwiML-Requests, wenn ein Anruf verbindet oder in ein Menü eintritt.
- WhatsApp-Messaging: eingehende und Status-Webhooks für die WhatsApp Business API.
- Conversations API: Message-added- und Teilnehmer-Events.
Schritt für Schritt: Twilio-Webhooks lokal testen
- Starte deine lokale App mit Twilio-Webhook-Routen (zum Beispiel
/sms/inbound). - Führe
npx portpreview 3000aus, um eine öffentliche HTTPS-URL zu erzeugen. - Setze in der Twilio-Konsole die Webhook-URL deiner Telefonnummer auf die Tunnel-URL plus deinen Routenpfad.
- Konfiguriere die HTTP-Methode (meist POST) und stelle sicher, dass der Content-Type zu deinem Handler passt.
- Sende eine Test-SMS oder tätige einen Testanruf, um den Webhook auszulösen.
- Inspiziere die erfasste Anfrage – Twilio sendet formularkodierte Payloads, kein JSON.
- Prüfe, dass dein Handler die Twilio-Signatur validiert und gültiges TwiML oder eine 2xx-Antwort zurückgibt.
Twilio-Request-Signaturen lokal validieren
Twilio signiert jeden Request mit einem X-Twilio-Signature-Header, der aus der vollständigen URL und den POST-Parametern mit deinem Auth-Token berechnet wird. Dein Handler sollte:
- die exakte öffentliche URL (inklusive Tunnel-Hostname) für die Signaturvalidierung verwenden.
- alle POST-Parameter an die Validierungsfunktion übergeben.
- Requests mit ungültiger Signatur ablehnen, auch beim lokalen Testen.
Wenn sich deine Tunnel-URL zwischen Sitzungen ändert, aktualisiere sowohl die Webhook-URL in der Twilio-Konsole als auch deine Validierungs-URL entsprechend.
Twilio-spezifische Debugging-Tipps
Formularkodierte Payloads
Anders als Stripe oder GitHub sendet Twilio application/x-www-form-urlencoded-Daten. Stelle sicher, dass dein Handler Form-Bodies korrekt parst, nicht nur JSON.
TwiML-Antworten
Voice- und SMS-Handler müssen gültiges TwiML-XML zurückgeben. Teste die Antwortformatierung lokal, bevor Twilio Zustellungen als fehlgeschlagen markiert.
Timeout-Verhalten
Twilio erwartet bei den meisten Webhooks Antworten innerhalb von 15 Sekunden. Langsame Handler verursachen Retries und Doppelzustellungen – nutze Webhook-Replay, um die Retry-Behandlung zu testen.
Status-Callback-Ketten
SMS-Workflows verketten oft eingehende Webhooks mit Status-Callbacks. Teste beide Endpunkte lokal, indem du separate Tunnel-Routen oder Pfade konfigurierst.
Twilio lokal testen vs. Twilio CLI
Die Twilio CLI kann eingehende Requests mit twilio phone-numbers:update und lokalen Tunnel-Plugins simulieren. Ein dedizierter Localhost-Tunnel mit Anfrageerfassung gibt dir dauerhafte Sichtbarkeit auf jeden Callback, Replay-Fähigkeit und einen Workflow, der über mehrere Provider skaliert – nicht nur Twilio.
Allgemeine Muster zum Webhook-Debugging findest du in So debuggst du Webhooks lokal.
Tritt der PortPreview-Warteliste bei für Twilio- und Multi-Provider-Webhook-Tests aus einem Tunnel.