Falla la validación de la firma de Twilio — descubre por qué

Comprueba una firma que Twilio rechazó

La cadena exacta que firma Twilio

Todo lo demás en esta página se deriva de esto. Twilio no firma tu cuerpo ni tus cabeceras. Firma una sola cadena, construida así:

1. Empieza por la URL completa a la que llamó Twilio: esquema, host, puerto si era explícito, ruta y query string.
2. Ordena los nombres de los parámetros POST en orden ASCII.
3. Para cada uno, añade el nombre seguido inmediatamente de su valor. Sin separador, sin signo igual, sin codificación, nada en medio.
4. Calcula el HMAC-SHA1 de toda la cadena con tu Auth Token.
5. Codifica el digest en Base64. Eso es X-Twilio-Signature.

Lo mismo con valores reales

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=

Fíjate en lo que no aparece. Ni &, ni =, ni codificación por porcentaje: el valor es +15017122661, no %2B15017122661. Quien reconstruye los parámetros troceando el cuerpo en bruto por su cuenta suele olvidarse de decodificar, y obtiene una firma errónea por un motivo que ningún mensaje de error va a mencionar.

Cambia un solo byte de esos 101 caracteres y la firma cambia por completo. Esa es toda la historia: tu código y Twilio tienen que construir exactamente la misma cadena, y cada proxy, router y middleware intermedio puede cambiarla sin avisarte.

Cuatro URL, cuatro firmas, una sola verdad

Mismo Auth Token, los mismos cuatro parámetros de arriba. Solo cambia la URL — y basta con eso:

Nada en el fallo te dice en cuál de las cuatro estás. Eso es lo que hace la herramienta: las calcula todas, hasta dieciséis formas de URL, y compara cada una con la firma que Twilio envió de verdad. La línea verde es la respuesta.

Las 8 causas reales

Ordenadas según la frecuencia con que aparecen en el foro de la comunidad de Twilio y en los hilos de StackOverflow sobre este error. Ese orden es nuestra lectura, no una estadística medida: tómalo como un orden de búsqueda, no como un hecho.

El bug de los parámetros repetidos — no es culpa tuya

Este merece su propia sección, porque puedes leer la documentación de Twilio durante una hora sin encontrarlo. La mensajería de grupo y Conversations envían la misma clave varias veces:

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

El servidor de Twilio ordena las claves y luego concatena. Tu mapa de parámetros contiene un array. twilio-node hace data += key + params[key], y JavaScript convierte ese array en cadena uniéndolo con comas — en orden de llegada. Si tu framework parseó las dos direcciones en un orden distinto del que usó el servidor de Twilio, las dos cadenas difieren y la validación falla. Mismo token, misma URL, mismos parámetros. Y falla igualmente.

// twilio-node issue #722
// Los parámetros repetidos te llegan como array; ordénalos antes de validar.
if (Array.isArray(params['MessagingBinding.Address'])) {
  params['MessagingBinding.Address'].sort();
}
const valid = twilio.validateRequest(authToken, signature, url, params);

La herramienta prueba los dos órdenes automáticamente. Si la línea ordenada sale en verde, has encontrado un bug en el SDK, no en tu código — y puedes dejar de releer tu handler.

Funciona en local, falla en producción

La historia más frecuente, y tiene una sola causa: en desarrollo, tu túnel entrega la petición a tu app con el mismo esquema que usó Twilio. En producción, Traefik, nginx o Cloudflare terminan el TLS y reenvían HTTP plano al puerto 3000. Tu framework informa de lo que ve en su socket — http:// — y firma una cadena que Twilio nunca construyó.

// Detrás de Traefik / nginx / Cloudflare
app.set('trust proxy', true);
// req.protocol ahora sigue a 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 ahora reconstruye https://
validator.validate(request.url, request.form, signature)

// app/Http/Middleware/TrustProxies.php
protected $proxies = '*';           // solo si el proxy es tuyo
protected $headers = Request::HEADER_X_FORWARDED_ALL;

Una línea, tres ecosistemas. Una vez que confías en el proxy, el framework lee X-Forwarded-Proto y X-Forwarded-Host, reconstruye https:// y la firma coincide. Confía solo en proxies que controles de verdad: con trust proxy en true, cualquier cosa que haya delante puede declarar el esquema que quiera.

Cuerpos JSON: bodySHA256

Los webhooks de Twilio son application/x-www-form-urlencoded por defecto — nunca JSON. Pero Conversations y Studio pueden enviar JSON, y entonces cambian las reglas: el cuerpo no está en los parámetros. Twilio lo hashea con SHA-256, añade ese hash a la URL como parámetro de query bodySHA256 y firma la URL con una lista de parámetros vacía.

const valid = twilio.validateRequestWithBody(
  process.env.TWILIO_AUTH_TOKEN,
  req.headers['x-twilio-signature'],
  fullUrl,        // debe seguir llevando ?bodySHA256=…
  rawBody         // la cadena en bruto, NO pasada por JSON.parse y re-stringify
);

Aquí hay dos trampas. Si quitas la query string de la URL, también quitas bodySHA256, y la comprobación falla sin mencionar nunca el cuerpo. Y si tu framework parseó el JSON antes de que llegaras, JSON.stringify() no te devolverá los bytes originales: el orden de las claves y los espacios se han perdido. Captura el cuerpo en bruto. El modo JSON de la herramienta de arriba muestra los dos hashes lado a lado para que veas cuál de las dos trampas te ha mordido.

Datos de Twilio que conviene tener presentes

Detalles que deciden si la firma llega siquiera a comprobarse:

• HMAC-SHA1, no SHA256. Stripe, GitHub y Shopify usan SHA-256, así que copiar un handler que funciona de uno de ellos y cambiar el nombre de la cabecera da un validador que nunca coincide con nada.
• El payload es application/x-www-form-urlencoded por defecto, nunca JSON. Si tu framework solo parsea cuerpos JSON, tu mapa de parámetros está vacío y todas las firmas fallan.
• Twilio espera 15 segundos por un webhook de voz y 5 segundos en Conversations. Valida primero, responde y después haz el trabajo lento: una comprobación de firma que se ejecuta después de una llamada a la base de datos puede agotar el tiempo antes de devolver.
• Un reintento por defecto, y hasta cinco con connection overrides. Así que una firma incorrecta no es un mensaje fallido: es un mensaje perdido tras un par de intentos.
• El Debugger conserva sus logs 30 días. Ahí encontrarás la URL a la que llamó Twilio de verdad, que es el dato que necesita esta página.
• En las conexiones WebSocket la cabecera llega en minúsculas: x-twilio-signature. Compara las cabeceras sin distinguir mayúsculas y minúsculas.

¿Y el error 57012 de Twilio?

El error 57012 (firma no válida) te dice que la firma no coincide con la que calculó Twilio y señala a los sospechosos habituales: token incorrecto, URL incorrecta, parámetros modificados por el camino, hash del cuerpo ausente. Todo cierto. Pero se detiene justo donde empieza la depuración, porque no puede decirte cuál se aplica a tu petición. Ten en cuenta además que, desde el lado de Twilio, las causas 1, 2, 3, 7 y 8 de arriba son todas «URL incorrecta»: cinco bugs distintos, cinco soluciones distintas, un solo código de error. Separarlos es el objetivo de esta página.

Cuándo usar qué — con honestidad

Aquí no somos la respuesta a todo, y fingir lo contrario te haría perder la tarde.

Si los webhooks son una parte permanente de tu stack y no un incendio que estás apagando, nuestro túnel Relay reenvía el tráfico real de Twilio a localhost, y el tester de webhooks de Twilio reenvía peticiones firmadas a tu handler para que compruebes el arreglo sin gastar un SMS real.

Preguntas frecuentes