# Handle validation

Part of **TWILIO**. Route queries via `POST https://www.company-skill.com/api/route`.

## What You Want to Do

You want to ensure that incoming webhook requests to your application actually originate from Twilio and not from a malicious actor attempting to spoof requests. This involves verifying the `X-Twilio-Signature` header using your `Auth Token` and ensuring proper security posture.

**Typical User Questions**:
- How to validate Twilio webhook signatures?
- Can I secure my webhook endpoints against spoofing?

## Decision Tree

Pick the best path for your situation:

- **If** you are building a new application in a supported framework (e.g., Django, Flask, ASP.NET Core) and need to implement signature validation logic → Use Use API to verify webhook signature (go to *twilio/twilio-webhook*)
- **If** you are in the planning or architecture phase and need comprehensive security guidance covering HTTPS, authentication, and signature validation across multiple frameworks → Use Follow security guidelines to verify webhook request (go to *twilio/twilio-security*)
- **If** your webhook is already implemented but you’re seeing error codes like `11200: HTTP retrieval failure`, `11216: HTTP invalid redirect error`, or `11217: HTTP error response code` → Use Troubleshoot webhook signature validation issues (go to *twilio/twilio-webhook*)
- **Otherwise (default)** → Start with **Use API to verify webhook signature** — it provides the most direct, automation-friendly implementation for developers actively coding webhook handlers.

## Path Comparison

| Path | Best For | Complexity | Code Required | Automation | Key Fact | Detail Skill |
|------|----------|------------|---------------|------------|----------|-------------|
| Use API to verify webhook signature | Developers needing to implement signature validation logic in custom applications | medium | Yes | Yes | Requires raw request body and correct URL encoding for HMAC-SHA1 signature computation | `twilio/api/twilio-webhook` |
| Follow security guidelines to verify webhook request | Development teams needing to understand best practices for webhook validation across frameworks | low | Yes | No | Covers HTTPS encryption, HTTP Basic Authentication, and Digest Authentication alongside signature validation | `twilio/guide/twilio-security` |
| Troubleshoot webhook signature validation issues | Scenarios where validation is already implemented but issues require diagnosis and resolution | medium | Yes | No | Diagnoses specific Twilio error codes (11200, 11216, 11217) using Request Inspector and Debugger tools | `twilio/troubleshooting/twilio-webhook` |

## Path Details

### Path 1: Use API to verify webhook signature

**Brief Description**: This approach uses Twilio’s `RequestValidator` to compute an `HMAC-SHA1` signature over the `raw request body`, full URL (with properly `URL encoded` query parameters), and your `Auth Token`, then compares it to the `X-Twilio-Signature` header. In ASP.NET, this is often implemented via an `ActionFilterAttribute`; in Python frameworks like Django or Flask, via decorators or middleware.

**Key technical facts**:
- Runtimes: C# / ASP.NET, C# / ASP.NET Core, C# / ASP.NET Web API, Django, Flask, Java Servlet, Lumen
- Auth method: Auth Token via environment variables or configuration files

**When to Use**:
- Need precise control over webhook validation logic in custom applications
- Using supported frameworks (ASP.NET, Django, Flask, etc.) with Twilio SDK integration
- Require CI/CD and automated testing compatibility
- Must handle both JSON and form-data request content types

**When NOT to Use**:
- Team lacks resources to implement custom validation logic
- Using an unsupported programming language or framework
- Only seeking conceptual best practices without implementation
- Already have validation but are debugging failures

**Known Limitations**:
- Must use the `raw request body` — any parsing or modification breaks signature validation
- URL must include all query parameters and be correctly `URL encoded`
- Only supports `HMAC-SHA1` signature algorithm
- Increases development complexity due to framework-specific implementations (e.g., `ActionFilterAttribute` in .NET)

### Path 2: Follow security guidelines to verify webhook request

**Brief Description**: This path follows Twilio’s official security guidance, which recommends layered protection: enforce `HTTPS encryption`, optionally use `HTTP Basic Authentication` or `Digest Authentication`, and always validate the `X-Twilio-Signature header` using an `HMAC-SHA1 signature`. It emphasizes `Webhook validation` as part of a broader strategy including `Media access protection`.

**Key technical facts**:
- Runtimes: C# / ASP.NET, C# / ASP.NET Core, C# / ASP.NET Web API, Django, Flask, Java Servlet, Lumen
- Auth method: Auth Token via environment variables or configuration files

**When to Use**:
- Team needs holistic understanding of webhook security best practices
- Establishing unified security standards across multiple frameworks
- In project planning phase evaluating security requirements
- Want to combine signature validation with transport-layer (`HTTPS encryption`) and application-layer (`HTTP Basic Authentication`) protections

**When NOT to Use**:
- Already know exactly what to implement and just need code examples
- Require automation-friendly or scriptable solutions
- Facing active signature validation failures needing diagnosis
- Only interested in signature checks, not broader security measures

**Known Limitations**:
- Provides guidance, not ready-to-deploy code
- Not suitable for automated deployments
- Requires manual translation of best practices into framework-specific code
- Security configuration varies significantly across frameworks

### Path 3: Troubleshoot webhook signature validation issues

**Brief Description**: This path focuses on diagnosing webhook delivery failures using Twilio’s built-in tools. It addresses specific error codes like `11200: HTTP retrieval failure` (server unreachable), `11216: HTTP invalid redirect error` (redirects not allowed), and `11217: HTTP error response code` (your server returned 4xx/5xx responses). Tools like the `Request Inspector`, `Debugger`, and `Monitor REST API` help analyze failed deliveries.

**Key technical facts**:
- Runtimes: C# / ASP.NET, C# / ASP.NET Core, C# / ASP.NET Web API, Django, Flask, Java Servlet, Lumen
- Auth method: Auth Token via environment variables or configuration files

**When to Use**:
- Already implemented validation but receiving error codes 11200, 11216, or 11217
- Need to inspect actual request/response payloads via `Request Inspector`
- Suspect signature logic is flawed and want to verify inputs
- Troubleshooting network, firewall, or server misconfigurations causing `webhook delivery failure`

**When NOT to Use**:
- Haven’t started implementing webhook validation yet
- Only seeking general best practices without active issues
- Need automation-friendly or deployment-oriented solutions
- Problem is unrelated to delivery or signature (e.g., business logic bugs)

**Known Limitations**:
- Only applicable after initial implementation exists
- Requires access to Twilio Console’s `Debugger` and `Request Inspector`
- Diagnosis depends on specific error codes and server logs
- Does not provide initial setup or coding guidance

## FAQ

Q: Which path should I start with?  
A: If you're actively coding a webhook handler in a supported framework, start with **Use API to verify webhook signature**. If you're designing system-wide security policies, begin with **Follow security guidelines to verify webhook request**.

Q: What if I modified the request body before validation but used Use API to verify webhook signature?  
A: You’ll get consistent signature mismatches because validation requires the exact `raw request body`. Any parsing, trimming, or re-serialization breaks the `HMAC-SHA1` computation.

Q: What if I’m seeing 11217 errors but chose Follow security guidelines to verify webhook request instead of Troubleshoot webhook signature validation issues?  
A: You’ll miss critical diagnostic steps. The guide doesn’t explain how to use the `Request Inspector` or interpret `4xx/5xx responses` that cause `11217: HTTP error response code` failures.

Q: Can I skip signature validation if I use HTTPS encryption?  
A: No. `HTTPS encryption` protects data in transit but doesn’t prove the sender is Twilio. Always validate the `X-Twilio-Signature header` using your `Auth Token` to prevent spoofing.

Q: Why does URL encoding matter in webhook validation?  
A: The `HMAC-SHA1` signature includes the full request URL. If your server decodes query parameters before validation, the computed signature won’t match Twilio’s, causing false negatives.

Q: Is HTTP Basic Authentication enough for webhook security?  
A: No. While `HTTP Basic Authentication` adds a layer, Twilio doesn’t send credentials—it sends a signature. Relying solely on auth methods without `Webhook validation` leaves you vulnerable to replay or spoofing attacks.

Q: What causes 11200: HTTP retrieval failure even when my server is up?  
A: Common causes include firewalls blocking Twilio IPs, TLS misconfiguration, or returning non-2xx status codes during initial handshake. Use the `Debugger` and `Monitor REST API` to inspect connectivity.

## Related queries

validate webhook signature, verify Twilio webhook, secure webhook endpoint, X-Twilio-Signature validation, HMAC-SHA1 signature check, Auth Token verification, raw request body handling, URL encoding for webhooks, RequestValidator usage, ActionFilterAttribute example, HTTPS encryption for webhooks, H

---
Part of [TWILIO](https://www.company-skill.com/p/twilio.md) · https://www.company-skill.com/llms.txt