Invalid URL

What this error means

Root causes

How to fix it

1. 1

   Capture and inspect the raw TwiML from your webhook

   Make a direct HTTP request to your webhook endpoint using curl or Postman and examine the raw XML response. Look for any URL attributes that are empty, contain 'localhost', contain unresolved template placeholders, or are missing the 'https://' prefix.

2. 2

   Ensure all URL attributes are absolute URLs with HTTPS

   TwiML URL attributes must be fully qualified absolute URLs beginning with 'https://' (or 'http://' for non-SSL, though HTTPS is strongly recommended). Relative paths such as '/handle-input' are not valid. Replace all relative paths with their absolute equivalents.

   // Incorrect — relative path will trigger 13224
   twiml.gather({ action: '/handle-input' });
   
   // Correct — fully qualified absolute URL
   const BASE_URL = process.env.BASE_URL; // e.g., 'https://yourdomain.com'
   twiml.gather({ action: `${BASE_URL}/handle-input` });

3. 3

   Validate environment variables for base URL at startup

   Add startup validation to ensure that all environment variables used to construct TwiML URLs are present and non-empty. Fail fast at application startup rather than producing invalid TwiML at runtime.

   // Validate required env vars at startup
   const requiredEnvVars = ['BASE_URL', 'TWILIO_ACCOUNT_SID', 'TWILIO_AUTH_TOKEN'];
   
   for (const varName of requiredEnvVars) {
     if (!process.env[varName]) {
       throw new Error(`Missing required environment variable: ${varName}`);
     }
     if (varName === 'BASE_URL' && !process.env[varName].startsWith('https://')) {
       throw new Error(`BASE_URL must start with https://`);
     }
   }
   console.log('Environment validation passed.');

4. 4

   Use ngrok or a similar tunneling tool for local development

   When developing locally, use ngrok to expose your local server with a public HTTPS URL. Configure your TwiML to use the ngrok URL so Twilio can reach your webhooks. Update your BASE_URL environment variable with the ngrok-provided URL when testing.

5. 5

   URL-encode any dynamic path or query string segments

   If your URLs include dynamic values (user IDs, call IDs, session tokens), ensure those values are properly URL-encoded before being injected into URL attributes. Use your language's built-in URL encoding function to prevent malformed URLs from special characters.

6. 6

   Test all TwiML URLs are accessible from a public IP

   From any machine (not your own network), confirm that every URL used in your TwiML is reachable and returns a valid response. Use an online tool such as https://www.uptrends.com/tools/url-checker or run a curl request from a cloud VM to simulate Twilio's request.

7. 7

   Add TwiML validation tests to your CI/CD pipeline

   Write integration tests that parse your webhook TwiML output and validate all URL attributes match the pattern of a fully qualified HTTPS URL. Run these tests on every pull request and deployment to catch broken URLs before they go live.

   // Jest test — validate all URL attributes in TwiML
   const URL_PATTERN = /^https:\/\/.+/;
   
   test('all TwiML URL attributes are absolute HTTPS URLs', async () => {
     const response = await request(app).post('/webhook');
     const xmlString = response.text;
     
     // Extract all URL-like attribute values
     const urlAttrs = xmlString.match(/(?:action|url|statusCallback|fallbackUrl)="([^"]+)"/g) || [];
     
     for (const attr of urlAttrs) {
       const url = attr.match(/"([^"]+)"/)[1];
       expect(url).toMatch(URL_PATTERN);
     }
   });

8. 8

   Check Twilio Debugger for the specific attribute and URL value

   Navigate to Monitor > Debugger in the Twilio Console and locate the 13224 error. The error details will show the exact attribute name and the URL value that failed validation. This gives you a precise string to fix rather than needing to scan your entire codebase.

Prevention

Prevent 13224 errors by centralizing all URL construction through a single utility function that validates and builds absolute HTTPS URLs from a BASE_URL environment variable. Never hardcode domain names or localhost addresses in TwiML generation code. Add startup validation for all URL-related environment variables so misconfiguration is caught immediately at deploy time rather than silently producing invalid TwiML. Integrate TwiML URL validation into your automated test suite so every deployment verifies that all webhook URLs are well-formed absolute HTTPS addresses. Use infrastructure-as-code to manage webhook URL configuration, ensuring it stays synchronized with your actual deployed service endpoints.