Test Twilio Webhooks Locally

From a stuck handler to a live Twilio delivery you can read and replay.

1. 1Start LocalCan and point it at your local server: localcan http 3000. It opens the tunnel and prints your .local domains plus a public HTTPS URL.
2. 2Grab your persistent URL — something like your-app-12.localcan.dev. It is saved to your project file and comes back identical after every restart, so you wire it up once.
3. 3Point your number at the LocalCan URL: in the Twilio Console go to Phone Numbers → Manage → Active Numbers → your number, and set the Messaging "A message comes in" and/or Voice "A call comes in" webhook to your URL with your path, e.g. https://your-app-12.localcan.dev/sms and /voice (method POST). For StatusCallbacks, pass that same base URL as the StatusCallback param when you send a message or call.
4. 4Easiest: text or call the number — a real inbound trigger hits your webhook. From the CLI you can repoint with twilio phone-numbers:update +1XXXXXXXXXX --sms-url=https://your-app-12.localcan.dev/sms, then send. To replay without spending a message, the twilio webhook:event plugin (@twilio-labs/plugin-webhook) emulates an SMS/voice request to your URL with a valid X-Twilio-Signature (or --no-signature to skip it).
5. 5Open Inspect Traffic in LocalCan. The delivery lands with full headers and body — expand it, fix your handler, and hit Replay to send the exact same request again. No new test event needed.

Header

X-Twilio-Signature

Algorithm

HMAC-SHA1, Base64-encoded

What's signed

Twilio signs the full request URL (scheme through the end of the query string), and for application/x-www-form-urlencoded POSTs it then appends every param as name immediately followed by value — params sorted by case-sensitive byte order (uppercase before lowercase, i.e. Object.keys().sort()), with NO delimiters between the URL or between params — then HMAC-SHA1 with your Auth Token and Base64-encodes the result. For application/json bodies there are no form params; Twilio instead appends ?bodySHA256=<hex sha256 of the raw body> to the URL, and you validate both the signature over that URL and that hex-SHA-256 of the raw body equals bodySHA256. If the URL your code reconstructs differs by one byte — scheme, host, port, trailing slash, or param encoding — the signature can never match.

Secret

The signing secret is your account's primary Auth Token from the Twilio Console (shown beside your Account SID) — an opaque 32-char hex-style string, no prefix, case-sensitive. Subaccounts have their own. Twilio supports a secondary Auth Token for zero-downtime rotation: deploy the secondary everywhere, then Promote it — promotion is instant and deletes the old primary immediately, so validate with the new primary right after promoting, not a still-secondary token.

import express from 'express'
import twilio from 'twilio'

const authToken = process.env.TWILIO_AUTH_TOKEN // primary Auth Token, no prefix
const app = express()

// Form-encoded webhooks (inbound SMS / voice / StatusCallback).
// Parse the urlencoded body so the validator can re-sort + concatenate the params.
app.post('/sms', express.urlencoded({ extended: false }), (req, res) => {
  const signature = req.headers['x-twilio-signature']

  // Rebuild the EXACT public URL Twilio signed. Behind a tunnel/proxy your app
  // sees http + an internal host, but Twilio signed https + your public domain.
  const proto = req.headers['x-forwarded-proto'] || req.protocol
  const host = req.headers['x-forwarded-host'] || req.headers.host
  const url = proto + '://' + host + req.originalUrl

  // validateRequest recomputes HMAC-SHA1(url + sorted-params), Base64, constant-time compare.
  const valid = twilio.validateRequest(authToken, signature, url, req.body)
  if (!valid) {
    return res.status(403).send('Invalid Twilio signature')
  }

  res.type('text/xml').send('<Response><Message>Got it</Message></Response>')
})

// JSON callbacks carry ?bodySHA256=...; you MUST pass the RAW body string,
// not a re-serialized object (key order / whitespace would change the hash).
app.post('/callback', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-twilio-signature']
  const proto = req.headers['x-forwarded-proto'] || req.protocol
  const host = req.headers['x-forwarded-host'] || req.headers.host
  const url = proto + '://' + host + req.originalUrl
  const rawBody = req.body.toString('utf8')

  // Checks the signature over the URL AND that sha256(rawBody) === bodySHA256.
  const valid = twilio.validateRequestWithBody(authToken, signature, url, rawBody)
  res.sendStatus(valid ? 200 : 403)
})