Twilio-handtekeningvalidatie mislukt — ontdek waarom

Controleer een handtekening die Twilio afwees

De exacte string die Twilio ondertekent

Alle andere secties op deze pagina volgen hieruit. Twilio ondertekent niet je body, en ook niet je headers. Het ondertekent één string, die zo wordt opgebouwd:

1. Begin met de volledige URL die Twilio aanriep: scheme, host, poort als die expliciet was, pad en de querystring.
2. Sorteer de namen van de POST-parameters in ASCII-volgorde.
3. Voeg voor elke parameter de naam toe, direct gevolgd door de waarde. Geen scheidingsteken, geen isgelijkteken, geen encoding, niets ertussen.
4. Bereken de HMAC-SHA1 van de hele string met je Auth Token.
5. Codeer de digest in base64. Dat is X-Twilio-Signature.

Hetzelfde met echte waarden

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=

Kijk wat er niet in staat. Geen &, geen =, geen percent-encoding: de waarde is +15017122661, niet %2B15017122661. Wie de params zelf opbouwt door de ruwe body te splitsen, vergeet meestal te decoderen en krijgt een handtekening die fout is om een reden die geen enkele foutmelding ooit noemt.

Verander één byte van die 101 tekens en de handtekening verandert volledig. Dat is het hele verhaal: je code en Twilio moeten exact dezelfde string opbouwen, en elke proxy, router en middleware daartussen kan die ongemerkt veranderen.

Vier URL's, vier handtekeningen, één waarheid

Zelfde Auth Token, zelfde vier params als hierboven. Alleen de URL verandert — en dat is genoeg:

Niets in de fout vertelt je welke van de vier het is. Dat doet de tool: hij berekent ze allemaal, tot zestien URL-vormen, en vergelijkt elk ervan met de handtekening die Twilio echt stuurde. De groene regel is het antwoord.

De 8 echte oorzaken

Gerangschikt naar hoe vaak ze opduiken op het Twilio-communityforum en in StackOverflow-threads over deze fout. Die volgorde is onze eigen lezing, geen gemeten statistiek — gebruik haar als zoekvolgorde, niet als feit.

De bug met herhaalde params — het ligt niet aan jou

Deze verdient een eigen sectie, want je kunt een uur in de docs van Twilio lezen zonder hem ooit te vinden. Groepsberichten en Conversations sturen dezelfde key meerdere keren:

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

De server van Twilio sorteert de keys en plakt ze daarna aan elkaar. Jouw params-map bevat een array. twilio-node doet data += key + params[key], en JavaScript zet die array om naar een string door de elementen met komma's samen te voegen — in volgorde van binnenkomst. Als je framework de twee adressen in een andere volgorde parste dan de server van Twilio gebruikte, verschillen de twee strings en faalt de validatie. Zelfde token, zelfde URL, zelfde params. Het faalt toch.

// twilio-node issue #722
// Herhaalde params komen binnen als array; sorteer ze vóór het valideren.
if (Array.isArray(params['MessagingBinding.Address'])) {
  params['MessagingBinding.Address'].sort();
}
const valid = twilio.validateRequest(authToken, signature, url, params);

De tool test beide volgordes automatisch. Wordt de gesorteerde regel groen, dan heb je een bug in de SDK gevonden, niet in je code — en kun je stoppen met je handler steeds opnieuw door te lezen.

Werkt lokaal, breekt in productie

Het meest voorkomende verhaal, en het heeft één oorzaak: in dev geeft je tunnel de request aan je app door met hetzelfde scheme dat Twilio gebruikte. In productie beëindigen Traefik, nginx of Cloudflare de TLS en sturen ze gewone HTTP door op poort 3000. Je framework meldt wat het op zijn socket ziet — http:// — en ondertekent een string die Twilio nooit heeft opgebouwd.

// Achter Traefik / nginx / Cloudflare
app.set('trust proxy', true);
// req.protocol volgt nu 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 bouwt nu weer https:// op
validator.validate(request.url, request.form, signature)

// app/Http/Middleware/TrustProxies.php
protected $proxies = '*';           // alleen als de proxy van jou is
protected $headers = Request::HEADER_X_FORWARDED_ALL;

Eén regel, drie ecosystemen. Zodra de proxy vertrouwd wordt, leest het framework X-Forwarded-Proto en X-Forwarded-Host, bouwt het https:// opnieuw op en matcht de handtekening. Vertrouw alleen proxy's die je echt beheert: met trust proxy op true kan alles upstream elk scheme claimen dat het wil.

JSON-bodies: bodySHA256

Twilio-webhooks zijn standaard application/x-www-form-urlencoded — nooit JSON. Maar Conversations en Studio kunnen JSON sturen, en dan veranderen de regels: de body zit helemaal niet in de params. Twilio hasht hem met SHA-256, voegt die hash als queryparameter bodySHA256 aan de URL toe en ondertekent de URL met een lege parameterlijst.

const valid = twilio.validateRequestWithBody(
  process.env.TWILIO_AUTH_TOKEN,
  req.headers['x-twilio-signature'],
  fullUrl,        // moet nog steeds ?bodySHA256=… bevatten
  rawBody         // de ruwe string, NIET eerst JSON.parse en dan weer stringify
);

Hier zitten twee valkuilen. Strip je de querystring van de URL, dan strip je ook bodySHA256, en faalt de controle zonder dat de body ooit genoemd wordt. En als je framework de JSON al parste voordat jij erbij kwam, geeft JSON.stringify() je de oorspronkelijke bytes niet terug — sleutelvolgorde en witruimte zijn weg. Vang de ruwe body af. De JSON-modus in de tool hierboven toont beide hashes naast elkaar, zodat je ziet welke van de twee je te pakken had.

Twilio-feiten om in je achterhoofd te houden

Details die bepalen of de handtekening überhaupt een kans krijgt om gecontroleerd te worden:

• HMAC-SHA1, niet SHA256. Stripe, GitHub en Shopify gebruiken allemaal SHA-256, dus wie een werkende handler van een van hen kopieert en alleen de headernaam vervangt, krijgt een validator die nooit iets matcht.
• De payload is standaard application/x-www-form-urlencoded, nooit JSON. Als je framework alleen JSON-bodies parst, is je params-map leeg en faalt elke handtekening.
• Twilio wacht 15 seconden op een voice-webhook, 5 seconden bij Conversations. Valideer eerst, antwoord, en doe daarna het trage werk — een handtekeningcontrole die na een databasecall draait, kan een time-out krijgen voordat hij terugkomt.
• Standaard één nieuwe poging, en tot vijf met connection overrides. Een foute handtekening is dus niet één mislukt bericht: het is één bericht dat na een paar pogingen verloren gaat.
• De Debugger bewaart zijn logs 30 dagen. Daar vind je de URL die Twilio echt aanriep, en dat is precies de input die deze pagina nodig heeft.
• Bij WebSocket-verbindingen komt de header in kleine letters binnen: x-twilio-signature. Vergelijk headers hoofdletterongevoelig.

En Twilio-fout 57012?

Fout 57012 (ongeldige handtekening) vertelt je dat de handtekening niet overeenkomt met de handtekening die Twilio berekende, en wijst naar de gebruikelijke verdachten: verkeerde token, verkeerde URL, params onderweg gewijzigd, body-hash ontbreekt. Allemaal waar. Maar het stopt precies waar het debuggen begint, want het kan je niet vertellen welke daarvan op jouw request van toepassing is. Let er ook op dat vanuit Twilio gezien de oorzaken 1, 2, 3, 7 en 8 hierboven allemaal gewoon “verkeerde URL” zijn — vijf verschillende bugs, vijf verschillende fixes, één foutcode. Die uit elkaar halen is het doel van deze pagina.

Wanneer gebruik je wat — eerlijk gezegd

We zijn hier niet het antwoord op alles, en doen alsof zou je middag verspillen.

Als webhooks een vast onderdeel van je stack zijn in plaats van een brand die je aan het blussen bent, stuurt onze Relay-tunnel echt Twilio-verkeer door naar localhost, en speelt de Twilio-webhooktester ondertekende requests af op je handler, zodat je de fix kunt checken zonder een echte sms te verbruiken.

Veelgestelde vragen