Validazione della firma Twilio fallita — scopri perché

Verifica una firma rifiutata da Twilio

La stringa esatta che Twilio firma

Tutto il resto di questa pagina discende da qui. Twilio non firma il tuo body né i tuoi header. Firma una sola stringa, costruita così:

1. Parti dall'URL completo chiamato da Twilio: schema, host, porta se era esplicita, path e query string.
2. Ordina i nomi dei parametri POST in ordine ASCII.
3. Per ciascuno, aggiungi il nome seguito subito dal suo valore. Nessun separatore, nessun segno di uguale, nessuna codifica, niente in mezzo.
4. Calcola l'HMAC-SHA1 dell'intera stringa con il tuo Auth Token.
5. Codifica il digest in Base64. Quello è X-Twilio-Signature.

La stessa cosa con valori reali

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=

Guarda cosa non c'è. Nessun &, nessun =, nessun percent-encoding: il valore è +15017122661, non %2B15017122661. Chi ricostruisce i parametri spezzando da solo il body grezzo di solito dimentica di decodificare, e ottiene una firma sbagliata per un motivo che nessun messaggio di errore menzionerà mai.

Cambia un solo byte di quei 101 caratteri e la firma cambia completamente. La storia è tutta qui: il tuo codice e Twilio devono costruire esattamente la stessa stringa, e ogni proxy, router e middleware in mezzo è libero di modificarla senza avvisarti.

Quattro URL, quattro firme, una sola verità

Stesso Auth Token, stessi quattro parametri di sopra. Cambia solo l'URL — e basta questo:

Nulla nell'errore ti dice in quale dei quattro casi ti trovi. È questo che fa lo strumento: li calcola tutti, fino a sedici forme di URL, e confronta ciascuna con la firma che Twilio ha davvero inviato. La riga verde è la risposta.

Le 8 vere cause

Ordinate in base a quanto spesso compaiono nel forum della community Twilio e nei thread StackOverflow su questo errore. Quest'ordine è una nostra lettura, non una statistica misurata — usalo come ordine di ricerca, non come un dato di fatto.

Il bug dei parametri ripetuti — non è colpa tua

Questo merita una sezione a sé, perché puoi leggere la documentazione di Twilio per un'ora senza mai trovarlo. I messaggi di gruppo e Conversations inviano la stessa chiave più volte:

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

Il server di Twilio ordina le chiavi, poi concatena. La tua mappa di parametri contiene un array. twilio-node fa data += key + params[key], e JavaScript converte quell'array in stringa unendo i valori con virgole — nell'ordine di arrivo. Se il tuo framework ha parsato i due indirizzi in un ordine diverso da quello usato dal server di Twilio, le due stringhe differiscono e la validazione fallisce. Stesso token, stesso URL, stessi parametri. Fallisce comunque.

// twilio-node issue #722
// I parametri ripetuti ti arrivano come array: ordinali prima di validare.
if (Array.isArray(params['MessagingBinding.Address'])) {
  params['MessagingBinding.Address'].sort();
}
const valid = twilio.validateRequest(authToken, signature, url, params);

Lo strumento testa entrambi gli ordini in automatico. Se la riga ordinata risulta verde, hai trovato un bug nell'SDK, non nel tuo codice — e puoi smettere di rileggere il tuo handler.

Funziona in locale, si rompe in produzione

La storia più comune in assoluto, e ha una sola causa: in sviluppo il tuo tunnel passa la richiesta alla tua app con lo stesso schema usato da Twilio. In produzione, Traefik, nginx o Cloudflare terminano il TLS e inoltrano HTTP semplice sulla porta 3000. Il tuo framework riporta ciò che vede sul suo socket — http:// — e firma una stringa che Twilio non ha mai costruito.

// Dietro Traefik / nginx / Cloudflare
app.set('trust proxy', true);
// req.protocol ora segue 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 ora ricostruisce https://
validator.validate(request.url, request.form, signature)

// app/Http/Middleware/TrustProxies.php
protected $proxies = '*';           // solo se il proxy è tuo
protected $headers = Request::HEADER_X_FORWARDED_ALL;

Una riga, tre ecosistemi. Una volta reso attendibile il proxy, il framework legge X-Forwarded-Proto e X-Forwarded-Host, ricostruisce https:// e la firma corrisponde. Rendi attendibili solo i proxy che controlli davvero: con trust proxy impostato a true, qualsiasi cosa a monte può dichiarare lo schema che vuole.

Body JSON: bodySHA256

I webhook di Twilio sono application/x-www-form-urlencoded per impostazione predefinita — mai JSON. Ma Conversations e Studio possono inviare JSON, e allora le regole cambiano: il body non è affatto nei parametri. Twilio ne calcola l'hash SHA-256, lo aggiunge all'URL come parametro di query bodySHA256 e firma l'URL con una lista di parametri vuota.

const valid = twilio.validateRequestWithBody(
  process.env.TWILIO_AUTH_TOKEN,
  req.headers['x-twilio-signature'],
  fullUrl,        // deve ancora contenere ?bodySHA256=…
  rawBody         // la stringa grezza, NON passata da JSON.parse e ri-serializzata
);

Qui ci sono due trappole. Togli la query string dall'URL e togli anche bodySHA256, così il controllo fallisce senza mai nominare il body. E se il tuo framework ha parsato il JSON prima di te, JSON.stringify() non ti restituirà i byte originali — ordine delle chiavi e spazi sono persi. Cattura il body grezzo. La modalità JSON dello strumento qui sopra mostra i due hash affiancati, così vedi quale delle due trappole ti ha colpito.

Dettagli su Twilio da tenere a mente

Dettagli che decidono se la firma avrà mai la possibilità di essere verificata:

• HMAC-SHA1, non SHA256. Stripe, GitHub e Shopify usano tutti SHA-256, quindi copiare un handler funzionante da uno di loro e cambiare solo il nome dell'header produce un validatore che non corrisponde mai a niente.
• Il payload è application/x-www-form-urlencoded per impostazione predefinita, mai JSON. Se il tuo framework parsa solo body JSON, la tua mappa di parametri è vuota e ogni firma fallisce.
• Twilio aspetta 15 secondi per un webhook vocale, 5 secondi su Conversations. Prima valida, poi rispondi, poi fai il lavoro lento — un controllo di firma eseguito dopo una query al database può andare in timeout prima di restituire.
• Un solo retry per impostazione predefinita, fino a cinque con i connection override. Quindi una firma errata non è un messaggio fallito: è un messaggio perso dopo un paio di tentativi.
• Il Debugger conserva i log per 30 giorni. È lì che trovi l'URL che Twilio ha davvero chiamato, cioè l'input che serve a questa pagina.
• Sulle connessioni WebSocket l'header arriva in minuscolo: x-twilio-signature. Confronta gli header senza distinguere maiuscole e minuscole.

E l'errore Twilio 57012?

L'errore 57012 (firma non valida) ti dice che la firma non corrisponde a quella calcolata da Twilio, e indica i soliti sospetti: token sbagliato, URL sbagliato, parametri modificati in transito, hash del body mancante. Tutto vero. Ma si ferma esattamente dove inizia il debug, perché non può dirti quale si applica alla tua richiesta. Nota anche che, dal lato di Twilio, le cause 1, 2, 3, 7 e 8 qui sopra sono tutte solo «URL sbagliato» — cinque bug diversi, cinque correzioni diverse, un solo codice di errore. Separarle è lo scopo di questa pagina.

Quando usare cosa — onestamente

Qui non siamo la risposta a tutto, e fingere il contrario ti farebbe solo perdere il pomeriggio.

Se i webhook sono una parte stabile del tuo stack e non un incendio da spegnere, il nostro tunnel Relay inoltra il traffico Twilio reale a localhost, e il tester di webhook Twilio rinvia richieste firmate al tuo handler, così puoi verificare la correzione senza spendere un vero SMS.

Domande frequenti