Twilio Webhook-Testguides

Replay + Signatur-Helper (Dashboard)

Open /dashboard or /dashboard/tunnels and use Webhook Command Center for this provider. It gives one-click replay and signature verification helpers.

instatunnel webhook verify --provider twilio --secret-env TWILIO_AUTH_TOKEN

curl -i -X POST "https://YOUR-SUBDOMAIN.instatunnel.my/webhooks/twilio/sms" -H "Content-Type: application/json" --data-binary @sample-twilio.json

Required signature header: x-twilio-signature

1. Lokales App-Setup

Create a local webhook endpoint at: /webhooks/twilio/sms

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

const app = express()
app.use(express.urlencoded({ extended: false }))

app.post('/webhooks/twilio/sms', (req, res) => {
  const signature = req.header('x-twilio-signature') || ''
  const url = process.env.PUBLIC_WEBHOOK_URL!
  const valid = twilio.validateRequest(
    process.env.TWILIO_AUTH_TOKEN!,
    signature,
    url,
    req.body
  )

  if (!valid) return res.status(403).send('invalid signature')

  console.log('sms from:', req.body.From, 'body:', req.body.Body)
  res.type('text/xml').send('<Response></Response>')
})

app.listen(3000, () => console.log('listening on :3000'))

2. InstaTunnel-Befehl ausfuhren

instatunnel 3000 --subdomain twilio-dev

Keep a fixed subdomain so your provider dashboard URL does not keep changing.

3. Provider-Felder zum Einfugen

Use the helper below to generate exact values with your chosen subdomain and path.

4. Testevent senden

1. Set your Twilio phone number webhook URL to the tunnel URL.
2. Send an SMS to that Twilio number from your phone.
3. Validate received payload and XML response in local logs.

5. Signatur prufen

Verify this header on every request: x-twilio-signature

const valid = twilio.validateRequest(
  process.env.TWILIO_AUTH_TOKEN!,
  req.header('x-twilio-signature')!,
  publicWebhookUrl,
  req.body
)
if (!valid) return res.status(403).send('invalid signature')

6. Retries und Idempotenz

• Use MessageSid/CallSid as idempotency keys.
• Return valid TwiML quickly to prevent repeated retries.
• Log signature validation errors separately from business logic errors.

7. Haufige Fehler und schnelle Fixes