Twilio Event Streams Setup Guide

Overview

Twilio Event Streams provides real-time error and warning notifications for all Twilio services. This replaces the legacy debugger webhook with a more scalable and reliable approach.

What We’re Monitoring

Based on your error analysis (twilio-error-analysis.txt), you have:

666 failed messages
666 undelivered messages
52.6% delivery rate (should be 95%+)
339 “unknown” errors with no details

Event Streams will help you:

✅ Get details on those “unknown” errors
✅ Catch errors in real-time
✅ Monitor A2P 10DLC compliance
✅ Track rate limits and API issues
✅ Improve your delivery rate

Architecture

Twilio detects an error
         ↓
Event Streams publishes event
         ↓
POST https://cfosilvia.com/api/twilio/events
         ↓
Validate signature
         ↓
Log to twilio_error_logs table
         ↓
Alert on critical errors

Files Created

1. `/app/api/twilio/events/route.ts`

Webhook endpoint for Event Streams

POST: Receives error events from Twilio
- Validates Twilio signature
- Parses CloudEvents format
- Logs to database
- Alerts on critical errors
GET: View recent error logs
- Returns last 50 errors
- Groups by type and level
- Useful for monitoring

2. `/sql-queries/create-twilio-error-logs-table.sql`

Database schema for error logs

CREATE TABLE twilio_error_logs (
  id UUID PRIMARY KEY,
  event_id TEXT UNIQUE,
  event_type TEXT,
  event_time TIMESTAMP,
  account_sid TEXT,
  level TEXT, -- "Error" or "Warning"
  payload JSONB,
  raw_event JSONB,
  created_at TIMESTAMP
)

3. `/scripts/setup-twilio-event-streams.sh`

Automated setup script Creates sink and subscriptions via Twilio CLI.

Setup Instructions

Step 1: Install Twilio CLI (if not already installed)

npm install -g twilio-cli

twilio login

Enter your Account SID and Auth Token when prompted.

Step 3: Create Database Table

Run the SQL in Supabase:

# Copy the SQL file contents
cat sql-queries/create-twilio-error-logs-table.sql

# Then paste and run in Supabase SQL Editor

Or use psql:

psql 'postgresql://postgres:[PASSWORD]@db.[PROJECT-ID].supabase.co:5432/postgres' \
  -f sql-queries/create-twilio-error-logs-table.sql

Step 4: Deploy the Endpoint

The endpoint is already created at /app/api/twilio/events/route.ts. Deploy to production:

git add .
git commit -m "Add Twilio Event Streams error monitoring"
git push

Wait for Vercel to deploy.

Step 5: Run Setup Script

./scripts/setup-twilio-event-streams.sh

This will:

Create a webhook sink pointing to your endpoint
Subscribe to messaging error events
Subscribe to voice error events
Display the Sink SID for reference

Output:

🎉 Twilio Event Streams Setup Complete!

Configuration:
  Webhook URL: https://www.cfosilvia.com/api/twilio/events
  Sink SID: DGxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Subscribed to:
  ✅ Messaging errors (SMS/MMS)
  ✅ Voice errors (calls)

Step 6: Test It

Trigger a test error: Send an SMS to an invalid number or trigger any Twilio error. Check if it worked:

# View in browser
open https://www.cfosilvia.com/api/twilio/events

# Or with curl
curl https://www.cfosilvia.com/api/twilio/events

Check database:

SELECT * FROM twilio_error_logs 
ORDER BY created_at DESC 
LIMIT 10;

Event Types

Messaging Errors

Type: com.twilio.messaging.error-log Common errors you’ll see:

Error 30034: Exceeded max price
Error 30007: Carrier violation
Error 21610: User opted out (STOP)
Error 21617: Queue overflow
Error 21408: Permission denied
Error 12300: Invalid number format

Voice Errors

Type: com.twilio.voice.error-log Common errors:

Call failures
Invalid phone numbers
TwiML errors
Connection issues

CloudEvents Format

Events arrive in CloudEvents format:

{
  "specversion": "1.0",
  "type": "com.twilio.messaging.error-log",
  "source": "/v1/Messaging/...",
  "id": "EZ00000000000000000000000000000000",
  "dataschema": "https://events-schemas.twilio.com/...",
  "datacontenttype": "application/json",
  "time": "2025-10-27T12:00:00.000Z",
  "data": "{\"account_sid\":\"AC...\",\"level\":\"Error\",\"payload\":{...}}"
}

Monitoring & Alerting

View Recent Errors

Via API:

curl https://www.cfosilvia.com/api/twilio/events

Via Database:

-- All errors today
SELECT * FROM twilio_error_logs 
WHERE event_time >= CURRENT_DATE 
ORDER BY event_time DESC;

-- Group by error type
SELECT 
  event_type,
  level,
  COUNT(*) as count
FROM twilio_error_logs
WHERE event_time >= CURRENT_DATE
GROUP BY event_type, level
ORDER BY count DESC;

-- Critical errors only
SELECT * FROM twilio_error_logs 
WHERE level = 'Error'
ORDER BY event_time DESC
LIMIT 20;

Add Alerting (Optional)

Edit /app/api/twilio/events/route.ts and add alerting:

// Alert on critical errors
if (level === 'Error') {
  // Send email
  await sendEmail({
    to: 'admin@cfosilvia.com',
    subject: 'Twilio Error Alert',
    body: JSON.stringify(eventData, null, 2)
  })
  
  // Or send to Slack
  await sendSlackMessage({
    channel: '#alerts',
    text: `🚨 Twilio Error: ${eventType}`,
    payload: eventData
  })
}

Managing Event Streams

List All Sinks

twilio api:events:v1:sinks:list

List All Subscriptions

twilio api:events:v1:subscriptions:list

Delete a Sink

twilio api:events:v1:sinks:remove --sid DGxxxxx

Delete a Subscription

twilio api:events:v1:subscriptions:remove --sid DFxxxxx

Update Sink URL

If you need to change the webhook URL:

twilio api:events:v1:sinks:update \
  --sid DGxxxxx \
  --sink-configuration '{"destination":"https://new-url.com/api/twilio/events","method":"POST"}'

Testing with ngrok

For local testing:

Start ngrok:
ngrok http 3000

Update the script: Edit scripts/setup-twilio-event-streams.sh:

WEBHOOK_URL="https://your-ngrok-url.ngrok-free.app/api/twilio/events"

Run setup:

./scripts/setup-twilio-event-streams.sh

Trigger an error and watch logs:

# In your dev server terminal
npm run dev

Troubleshooting

Events not arriving

Check sink status:

twilio api:events:v1:sinks:fetch --sid DGxxxxx

Check subscriptions:

twilio api:events:v1:subscriptions:list

Test the endpoint:

curl -X POST https://www.cfosilvia.com/api/twilio/events \
  -H "Content-Type: application/json" \
  -d '[{"type":"test","id":"test123","data":"{}"}]'

Check Vercel logs: Go to Vercel Dashboard → Logs → Filter by /api/twilio/events

Signature validation failing

Ensure TWILIO_AUTH_TOKEN is set in environment variables
Check that the URL in Twilio matches exactly (including https://)
Verify no proxy or CDN is modifying the request

Database errors

Ensure twilio_error_logs table exists
Check Supabase service role key is set
Verify database connection

Benefits

Before Event Streams:

❌ No visibility into account-level errors
❌ Manual checking of Twilio Console
❌ 339 “unknown” errors with no details
❌ Reactive debugging after users complain

After Event Streams:

✅ Real-time error notifications
✅ Automatic logging to database
✅ Detailed error information
✅ Proactive monitoring and alerting
✅ Historical error tracking
✅ Ability to analyze trends

Cost

Event Streams is free for error logs! No additional charges beyond your normal Twilio usage.

Next Steps

✅ Create database table
✅ Deploy endpoint to production
✅ Run setup script
✅ Test with a triggered error
⏭️ Add alerting (optional)
⏭️ Create dashboard for error visualization (optional)
⏭️ Set up automated reports (optional)

Resources

Status: Ready to deploy and configure

​Twilio Event Streams Setup Guide

​Overview

​What We’re Monitoring

​Architecture

​Files Created

​1. /app/api/twilio/events/route.ts

​2. /sql-queries/create-twilio-error-logs-table.sql

​3. /scripts/setup-twilio-event-streams.sh

​Setup Instructions

​Step 1: Install Twilio CLI (if not already installed)

​Step 2: Login to Twilio

​Step 3: Create Database Table

​Step 4: Deploy the Endpoint

​Step 5: Run Setup Script

​Step 6: Test It

​Event Types

​Messaging Errors

​Voice Errors

​CloudEvents Format

​Monitoring & Alerting

​View Recent Errors

​Add Alerting (Optional)

​Managing Event Streams

​List All Sinks

​List All Subscriptions

​Delete a Sink

​Delete a Subscription

​Update Sink URL

​Testing with ngrok

​Troubleshooting

​Events not arriving

​Signature validation failing

​Database errors

​Benefits

​Before Event Streams:

​After Event Streams:

​Cost

​Next Steps

​Resources