Twilio-Signaturprüfung fehlgeschlagen — finde heraus, warum

Eine von Twilio abgelehnte Signatur prüfen

Der exakte String, den Twilio signiert

Alle anderen Abschnitte dieser Seite ergeben sich aus diesem. Twilio signiert weder deinen Body noch deine Headers. Es signiert einen einzigen String, der so aufgebaut wird:

1. Beginne mit der vollständigen URL, die Twilio aufgerufen hat: Schema, Host, Port (falls explizit), Pfad und Query-String.
2. Sortiere die Namen der POST-Parameter in ASCII-Reihenfolge.
3. Hänge für jeden den Namen an, direkt gefolgt von seinem Wert. Kein Trennzeichen, kein Gleichheitszeichen, keine Kodierung, nichts dazwischen.
4. Bilde über den ganzen String einen HMAC-SHA1 mit deinem Auth Token.
5. Kodiere den Digest in Base64. Das ist X-Twilio-Signature.

Dasselbe mit echten Werten

https://api.example.com/twilio/sms

AccountSid=AC1234567890abcdef
Body=Hello
From=%2B15017122661
To=%2B15558675310

https://api.example.com/twilio/smsAccountSidAC1234567890abcdefBodyHelloFrom+15017122661To+15558675310

12345678901234567890123456789012

REsmqJpWLoqe1Q/VJXTZjx4eviY=

Achte darauf, was nicht drinsteht. Kein &, kein =, kein Percent-Encoding: Der Wert ist +15017122661, nicht %2B15017122661. Wer die Parameter selbst durch Aufsplitten des rohen Bodys rekonstruiert, vergisst meist das Dekodieren — und bekommt eine Signatur, die aus einem Grund falsch ist, den keine Fehlermeldung je nennen wird.

Ändere ein Byte dieser 101 Zeichen, und die Signatur ändert sich komplett. Das ist die ganze Geschichte: Dein Code und Twilio müssen exakt denselben String bauen, und jeder Proxy, Router und jede Middleware dazwischen kann ihn ändern, ohne dir Bescheid zu sagen.

Vier URLs, vier Signaturen, eine Wahrheit

Derselbe Auth Token, dieselben vier Parameter wie oben. Nur die URL ändert sich — und das reicht schon:

Nichts am Fehler verrät dir, bei welcher der vier du bist. Genau das macht das Tool: Es berechnet sie alle, bis zu sechzehn URL-Formen, und vergleicht jede mit der Signatur, die Twilio tatsächlich gesendet hat. Die grüne Zeile ist die Antwort.

Die 8 echten Ursachen

Sortiert danach, wie oft sie im Twilio-Community-Forum und in StackOverflow-Threads zu diesem Fehler auftauchen. Diese Reihenfolge ist unsere Lesart, keine gemessene Statistik — nimm sie als Suchreihenfolge, nicht als Fakt.

Der Bug mit wiederholten Parametern — nicht deine Schuld

Dieser verdient einen eigenen Abschnitt, denn du kannst eine Stunde in Twilios Doku lesen und ihn nie finden. Gruppennachrichten und Conversations senden denselben Key mehrfach:

MessagingBinding.Address=%2B15558675310&MessagingBinding.Address=%2B15017122661

Twilios Server sortiert die Keys und verkettet dann. Deine Parameter-Map enthält ein Array. twilio-node macht data += key + params[key], und JavaScript wandelt dieses Array in einen String um, indem es die Elemente mit Kommas verbindet — in Ankunftsreihenfolge. Hat dein Framework die beiden Adressen in einer anderen Reihenfolge geparst als Twilios Server, unterscheiden sich die beiden Strings, und die Prüfung scheitert. Derselbe Token, dieselbe URL, dieselben Parameter. Scheitert trotzdem.

// twilio-node issue #722
// Wiederholte Parameter kommen als Array an; vor der Prüfung sortieren.
if (Array.isArray(params['MessagingBinding.Address'])) {
  params['MessagingBinding.Address'].sort();
}
const valid = twilio.validateRequest(authToken, signature, url, params);

Das Tool testet beide Reihenfolgen automatisch. Wird die sortierte Zeile grün, hast du einen Bug im SDK gefunden, nicht in deinem Code — und kannst aufhören, deinen Handler zum zehnten Mal zu lesen.

Klappt lokal, bricht in Produktion

Die mit Abstand häufigste Geschichte, und sie hat eine einzige Ursache: In der Entwicklung übergibt dein Tunnel den Request mit demselben Schema an deine App, das Twilio verwendet hat. In Produktion terminieren Traefik, nginx oder Cloudflare TLS und leiten reines HTTP auf Port 3000 weiter. Dein Framework meldet, was es auf seinem Socket sieht — http:// — und signiert einen String, den Twilio nie gebaut hat.

// Hinter Traefik / nginx / Cloudflare
app.set('trust proxy', true);
// req.protocol folgt jetzt X-Forwarded-Proto
const url = req.protocol + '://' + req.get('host') + req.originalUrl;

from werkzeug.middleware.proxy_fix import ProxyFix
app.wsgi_app = ProxyFix(app.wsgi_app, x_proto=1, x_host=1)
# request.url rekonstruiert jetzt https://
validator.validate(request.url, request.form, signature)

// app/Http/Middleware/TrustProxies.php
protected $proxies = '*';           // nur, wenn der Proxy dir gehört
protected $headers = Request::HEADER_X_FORWARDED_ALL;

Eine Zeile, drei Ökosysteme. Sobald dem Proxy vertraut wird, liest das Framework X-Forwarded-Proto und X-Forwarded-Host, rekonstruiert https://, und die Signatur passt. Vertrau nur Proxys, die du wirklich kontrollierst: Mit trust proxy auf true kann alles davor jedes beliebige Schema behaupten.

JSON-Bodys: bodySHA256

Twilio-Webhooks sind standardmäßig application/x-www-form-urlencoded — nie JSON. Conversations und Studio können aber JSON senden, und dann ändern sich die Regeln: Der Body steckt gar nicht in den Parametern. Twilio hasht ihn mit SHA-256, hängt diesen Hash als Query-Parameter bodySHA256 an die URL und signiert die URL mit einer leeren Parameterliste.

const valid = twilio.validateRequestWithBody(
  process.env.TWILIO_AUTH_TOKEN,
  req.headers['x-twilio-signature'],
  fullUrl,        // muss weiterhin ?bodySHA256=… enthalten
  rawBody         // der rohe String, NICHT per JSON.parse geparst und neu serialisiert
);

Hier lauern zwei Fallen. Entfernst du den Query-String aus der URL, entfernst du auch bodySHA256, und die Prüfung scheitert, ohne den Body je zu erwähnen. Und hat dein Framework das JSON schon geparst, bevor du drankommst, gibt dir JSON.stringify() die Original-Bytes nicht zurück — Key-Reihenfolge und Leerzeichen sind weg. Erfasse den rohen Body. Der JSON-Modus im Tool oben zeigt beide Hashes nebeneinander, damit du siehst, welche der beiden dich erwischt hat.

Twilio-Fakten, die du im Kopf haben solltest

Details, die entscheiden, ob die Signatur überhaupt eine Chance bekommt, geprüft zu werden:

• HMAC-SHA1, nicht SHA256. Stripe, GitHub und Shopify nutzen alle SHA-256 — wer einen funktionierenden Handler von einem davon kopiert und nur den Header-Namen tauscht, bekommt einen Validator, der nie etwas matcht.
• Die Payload ist standardmäßig application/x-www-form-urlencoded, nie JSON. Parst dein Framework nur JSON-Bodys, ist deine Parameter-Map leer, und jede Signatur scheitert.
• Twilio wartet bei einem Voice-Webhook 15 Sekunden, bei Conversations 5 Sekunden. Erst prüfen, antworten, dann die langsame Arbeit erledigen — eine Signaturprüfung nach einem Datenbankaufruf kann in den Timeout laufen, bevor sie zurückkommt.
• Standardmäßig ein Retry, mit Connection Overrides bis zu fünf. Eine falsche Signatur ist also nicht eine fehlgeschlagene Nachricht, sondern eine Nachricht, die nach ein paar Versuchen verloren ist.
• Der Debugger bewahrt seine Logs 30 Tage auf. Dort findest du die URL, die Twilio tatsächlich aufgerufen hat — genau der Input, den diese Seite braucht.
• Bei WebSocket-Verbindungen kommt der Header kleingeschrieben an: x-twilio-signature. Vergleiche Header-Namen ohne Beachtung der Groß-/Kleinschreibung.

Und der Twilio-Fehler 57012?

Fehler 57012 (ungültige Signatur) sagt dir, dass die Signatur nicht zu der passt, die Twilio berechnet hat, und nennt die üblichen Verdächtigen: falscher Token, falsche URL, unterwegs geänderte Parameter, fehlender Body-Hash. Alles richtig. Aber er hört genau dort auf, wo das Debugging anfängt, denn er kann dir nicht sagen, was davon auf deinen Request zutrifft. Beachte außerdem: Aus Twilios Sicht sind die Ursachen 1, 2, 3, 7 und 8 oben alle nur „falsche URL“ — fünf verschiedene Bugs, fünf verschiedene Lösungen, ein Fehlercode. Sie auseinanderzuhalten ist der Zweck dieser Seite.

Wann was — ehrlich

Wir sind hier nicht die Antwort auf alles, und so zu tun, würde dir den Nachmittag kosten.

Sind Webhooks ein fester Teil deines Stacks und nicht nur ein Brand, den du gerade löschst, leitet unser Relay-Tunnel echten Twilio-Traffic an localhost weiter, und der Twilio-Webhook-Tester spielt signierte Requests gegen deinen Handler ab, damit du den Fix prüfen kannst, ohne eine echte SMS zu verbrauchen.

Häufige Fragen