Signature Twilio invalide — trouvez pourquoi

Vérifier une signature refusée par votre code

La chaîne exacte que Twilio signe

Tout le reste de la page découle d'ici. Twilio ne signe ni votre corps de requête, ni vos headers. Il signe une chaîne, construite comme ceci :

1. Partir de l'URL complète appelée par Twilio : schéma, hôte, port s'il était explicite, chemin, et la query string.
2. Trier les noms des paramètres POST par ordre ASCII.
3. Pour chacun, coller le nom suivi immédiatement de sa valeur. Aucun séparateur, aucun signe égal, aucun encodage, rien entre les deux.
4. Passer toute la chaîne en HMAC-SHA1 avec votre Auth Token.
5. Encoder le digest en base64. C'est X-Twilio-Signature.

La même chose avec de vraies valeurs

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=

Regardez ce qui n'y est pas. Pas de &, pas de =, pas de pourcent-encodage : la valeur est +15017122661, pas %2B15017122661. Ceux qui reconstruisent les params en découpant le corps brut à la main oublient en général de décoder, et obtiennent une signature fausse pour une raison qu'aucun message d'erreur ne mentionnera jamais.

Changez un octet de ces 101 caractères et la signature change entièrement. Toute l'affaire est là : votre code et Twilio doivent construire exactement la même chaîne, et chaque proxy, routeur ou middleware entre les deux a le droit de la modifier sans vous prévenir.

Quatre URL, quatre signatures, une seule vraie

Même Auth Token, mêmes quatre params que ci-dessus. Seule l'URL bouge — et ça suffit :

Rien dans l'échec ne vous dit sur laquelle des quatre vous êtes. C'est le travail de l'outil : il les calcule toutes, jusqu'à seize formes d'URL, et compare chacune à la signature réellement envoyée par Twilio. La ligne verte est la réponse.

Les 8 causes réelles

Classées selon leur fréquence d'apparition sur le forum communautaire Twilio et dans les fils StackOverflow sur cette erreur. Ce classement est notre lecture, pas une statistique mesurée : prenez-le comme un ordre de recherche, pas comme un fait.

Le bug des params répétés — ce n'est pas votre faute

Celui-là mérite sa section, parce que vous pouvez lire la doc Twilio pendant une heure sans jamais le trouver. Le group messaging et Conversations envoient la même clé plusieurs fois :

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

Le serveur Twilio trie les clés puis concatène. Votre map de params, elle, contient un tableau. twilio-node fait data += key + params[key], et JavaScript convertit ce tableau en chaîne en le joignant par des virgules — dans l'ordre d'arrivée. Si votre framework a parsé les deux adresses dans un ordre différent de celui du serveur Twilio, les deux chaînes divergent et la validation échoue. Même token, même URL, mêmes params. Ça échoue quand même.

// twilio-node issue #722
// Les params répétés arrivent en tableau ; trier avant de valider.
if (Array.isArray(params['MessagingBinding.Address'])) {
  params['MessagingBinding.Address'].sort();
}
const valid = twilio.validateRequest(authToken, signature, url, params);

L'outil teste les deux ordres automatiquement. Si la ligne triée ressort en vert, vous avez trouvé un bug du SDK et pas de votre code — et vous pouvez arrêter de relire votre handler.

Ça marche en local, ça casse en prod

L'histoire la plus fréquente, et elle a une seule cause : en dev, votre tunnel remet la requête à votre app sur le même schéma que celui utilisé par Twilio. En prod, Traefik, nginx ou Cloudflare terminent le TLS et transmettent du HTTP simple sur le port 3000. Votre framework rapporte ce qu'il voit sur sa socket — http:// — et signe une chaîne que Twilio n'a jamais construite.

// Derrière Traefik / nginx / Cloudflare
app.set('trust proxy', true);
// req.protocol suit maintenant 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 reconstruit maintenant du https://
validator.validate(request.url, request.form, signature)

// app/Http/Middleware/TrustProxies.php
protected $proxies = '*';           // seulement si le proxy est le vôtre
protected $headers = Request::HEADER_X_FORWARDED_ALL;

Une ligne, trois écosystèmes. Une fois le proxy déclaré de confiance, le framework lit X-Forwarded-Proto et X-Forwarded-Host, reconstruit https://, et la signature matche. Ne faites confiance qu'aux proxies que vous contrôlez vraiment : avec trust proxy à true, n'importe quoi en amont peut annoncer le schéma qu'il veut.

Corps JSON : bodySHA256

Les webhooks Twilio sont en application/x-www-form-urlencoded par défaut — jamais en JSON. Mais Conversations et Studio peuvent envoyer du JSON, et là les règles changent : le corps n'est plus du tout dans les params. Twilio le hashe en SHA-256, colle ce hash dans l'URL sous forme d'un paramètre de query bodySHA256, et signe l'URL avec une liste de params vide.

const valid = twilio.validateRequestWithBody(
  process.env.TWILIO_AUTH_TOKEN,
  req.headers['x-twilio-signature'],
  fullUrl,        // doit toujours porter ?bodySHA256=…
  rawBody         // la chaîne brute, PAS un JSON.parse puis re-stringify
);

Deux pièges. Retirez la query string de l'URL et vous retirez aussi bodySHA256 : la vérification échoue sans jamais parler du corps. Et si votre framework a parsé le JSON avant vous, JSON.stringify() ne vous rendra pas les octets d'origine — l'ordre des clés et les espaces ont disparu. Capturez le corps brut. Le mode JSON de l'outil affiche les deux hashs côte à côte, vous verrez lequel des deux vous a mordu.

Les faits Twilio à avoir en tête

Des détails qui décident si la signature a seulement une chance d'être vérifiée :

• HMAC-SHA1, pas SHA256. Stripe, GitHub et Shopify utilisent tous SHA-256 : copier un handler qui marche chez l'un et changer le nom du header donne un validateur qui ne matchera jamais rien.
• Le payload est en application/x-www-form-urlencoded par défaut, jamais en JSON. Si votre framework ne parse que les corps JSON, votre map de params est vide et toutes les signatures échouent.
• Twilio attend 15 secondes pour un webhook voix, 5 secondes sur Conversations. Validez d'abord, répondez, puis faites le travail lent — une vérification de signature placée après un appel base de données peut expirer avant de rendre la main.
• Un retry par défaut, jusqu'à cinq avec les connection overrides. Une signature fausse, ce n'est donc pas un message en échec : c'est un message perdu après deux ou trois tentatives.
• Le Debugger garde ses logs 30 jours. C'est là que vous trouverez l'URL réellement appelée par Twilio, celle dont cette page a besoin.
• Sur les connexions WebSocket, le header arrive en minuscules : x-twilio-signature. Comparez les noms de headers sans tenir compte de la casse.

Et l'erreur Twilio 57012 ?

L'erreur 57012 (signature invalide) vous dit que la signature ne correspond pas à celle calculée par Twilio, et pointe les suspects habituels : mauvais token, mauvaise URL, params modifiés en route, hash du corps manquant. Tout est vrai. Mais elle s'arrête exactement là où le débogage commence, puisqu'elle ne peut pas vous dire lequel s'applique à votre requête. Notez aussi que, vu de Twilio, les causes 1, 2, 3, 7 et 8 ci-dessus sont toutes « mauvaise URL » : cinq bugs différents, cinq corrections différentes, un seul code d'erreur. Les séparer, c'est l'objet de cette page.

Quoi utiliser, honnêtement

On n'est pas la réponse à tout ici, et prétendre le contraire vous ferait perdre l'après-midi.

Si les webhooks sont une brique permanente de votre stack et pas un incendie que vous éteignez, notre tunnel Relay transmet le vrai trafic Twilio vers localhost, et le testeur de webhook Twilio rejoue des requêtes signées vers votre handler pour vérifier le correctif sans dépenser un vrai SMS.

Questions fréquentes