twilio-webhook-architecture

What this skill does

## Overview

Twilio delivers events to your application via HTTP callbacks (webhooks). Inbound messages and calls trigger webhooks that expect a TwiML response; status callbacks and event streams push delivery and lifecycle data asynchronously. This skill covers the cross-product patterns that apply to every webhook integration.

---

## Prerequisites

- Twilio account with a phone number or service configured with a webhook URL
  -- New to Twilio? See `twilio-account-setup`
- `TWILIO_ACCOUNT_SID` and `TWILIO_AUTH_TOKEN` -- see `twilio-iam-auth-setup`
- SDK: `pip install twilio flask` / `npm install twilio express`
- Publicly accessible HTTPS endpoint (see Local Development section below)

---

## Quickstart

Receive an inbound SMS and validate the request signature before replying.

**Python (Flask)**
```python
import os
from flask import Flask, request, abort
from twilio.request_validator import RequestValidator
from twilio.twiml.messaging_response import MessagingResponse

app = Flask(__name__)
validator = RequestValidator(os.environ["TWILIO_AUTH_TOKEN"])

@app.route("/sms", methods=["POST"])
def incoming_sms():
    sig = request.headers.get("X-Twilio-Signature", "")
    if not validator.validate(request.url, request.form, sig):
        abort(403)
    resp = MessagingResponse()
    resp.message(f"Got: {request.form.get('Body')}")
    return str(resp), 200, {"Content-Type": "text/xml"}
```

**Node.js (Express)**
```node
const express = require("express");
const twilio = require("twilio");
const app = express();
app.use(express.urlencoded({ extended: false }));

app.post("/sms", (req, res) => {
    const valid = twilio.validateRequest(
        process.env.TWILIO_AUTH_TOKEN,
        req.headers["x-twilio-signature"],
        `https://${req.headers.host}${req.originalUrl}`,
        req.body
    );
    if (!valid) return res.status(403).send("Forbidden");
    const twiml = new twilio.twiml.MessagingResponse();
    twiml.message(`Got: ${req.body.Body}`);
    res.type("text/xml").send(twiml.toString());
});
```

Set your webhook URL in Console: **Phone Numbers > Active Numbers > (your number) > Messaging > "A Message Comes In"**.

---

## Key Patterns

### 1. Webhook Types Across Products

| Webhook type | Trigger | Expected response | Products |
|---|---|---|---|
| Inbound event | Message received / call answered | TwiML (XML) | Messaging, Voice |
| Status callback | Resource state change | `200` or `204` (no body required) | Messaging, Voice, Verify, Video |
| Action URL | TwiML verb completes (`<Gather>`, `<Record>`) | Next TwiML | Voice |
| Recording status | Recording processing completes | `200` or `204` | Voice |
| Debugger event | Error or warning on account | `200` or `204` | All |
| Event Streams | Any subscribed event | `200` or `204` | All (via Sink) |

### 2. Signature Validation

Twilio signs every webhook with an `X-Twilio-Signature` header (HMAC-SHA1 using your Auth Token). Always validate before processing.

**Form-encoded requests (`application/x-www-form-urlencoded`):**

Pass the full URL and POST body parameters to the validator.

**Python**
```python
from twilio.request_validator import RequestValidator

validator = RequestValidator(os.environ["TWILIO_AUTH_TOKEN"])
is_valid = validator.validate(request.url, request.form, request.headers.get("X-Twilio-Signature", ""))
```

**Node.js**
```node
const { validateRequest } = require("twilio");

const isValid = validateRequest(
    process.env.TWILIO_AUTH_TOKEN,
    req.headers["x-twilio-signature"],
    `https://${req.headers.host}${req.originalUrl}`,
    req.body
);
```

**JSON requests (`application/json`):**

Twilio appends a `bodySHA256` query parameter to your URL. Use the SDK's JSON-specific validation.

**Python**
```python
from twilio.request_validator import RequestValidator

validator = RequestValidator(os.environ["TWILIO_AUTH_TOKEN"])
is_valid = validator.validate_body(
    request.url,
    request.get_data(as_text=True),
    request.headers.get("X-Twilio-Signature", "")
)
```

**Node.js**
```node
const twilio = require("twilio");

// Use express.raw() or a verify callback to preserve the raw body
const isValid = twilio.validateRequestWithBody(
    process.env.TWILIO_AUTH_TOKEN,
    req.headers["x-twilio-signature"],
    `https://${req.headers.host}${req.originalUrl}`,
    req.rawBody  // must be the exact bytes Twilio sent, not JSON.stringify(req.body)
);
```

**Critical:** Use the SDK validator. Do not implement your own -- Twilio may add parameters without notice, and the exact algorithm (including port handling) has edge cases the SDK handles.

### 3. Status Callback Handling

Status callbacks are asynchronous POST requests Twilio sends when a resource changes state. They do not expect TwiML -- return `200` or `204`.

**Messaging status flow:** `queued` -> `sent` -> `delivered` (or `undelivered` / `failed`)

When using Messaging Services, the flow starts with `accepted` -> `queued` -> ...

**Voice status events:** `initiated`, `ringing`, `answered`, `completed`

Subscribe to specific events via `StatusCallbackEvent` parameter.

Status callbacks are signed with `X-Twilio-Signature` like all Twilio webhooks. Validate before acting on the payload -- an unvalidated endpoint lets anyone forge delivery status and drive downstream logic.

**Python (Flask) -- messaging status handler**
```python
@app.route("/status", methods=["POST"])
def message_status():
    sig = request.headers.get("X-Twilio-Signature", "")
    if not validator.validate(request.url, request.form, sig):
        return "Forbidden", 403
    sid = request.form.get("MessageSid")
    status = request.form.get("MessageStatus")
    error_code = request.form.get("ErrorCode")
    if status in ("failed", "undelivered") and error_code:
        print(f"Delivery failed {sid}: error {error_code}")
    return "", 204
```

**Node.js (Express) -- voice status handler**
```node
app.post("/call-status", (req, res) => {
    const valid = twilio.validateRequest(
        process.env.TWILIO_AUTH_TOKEN,
        req.headers["x-twilio-signature"],
        `https://${req.headers.host}${req.originalUrl}`,
        req.body
    );
    if (!valid) return res.status(403).send("Forbidden");
    const { CallSid, CallStatus, Duration } = req.body;
    console.log(`${CallSid}: ${CallStatus} (${Duration}s)`);
    res.sendStatus(204);
});
```

**Attach status callbacks when creating resources:**

```python
# Messaging
message = client.messages.create(
    to="+15558675310", from_="+15017122661", body="Hello!",
    status_callback="https://yourapp.com/status"
)

# Voice
call = client.calls.create(
    to="+15558675310", from_="+15017122661",
    url="https://yourapp.com/voice",
    status_callback="https://yourapp.com/call-status",
    status_callback_event=["initiated", "ringing", "answered", "completed"],
    status_callback_method="POST"
)
```

### 4. Connection Overrides (Retry and Timeout Tuning)

Append URL fragments to any webhook URL to override default connection behavior. Fragments are not included in signature computation.

**Format:** `https://yourapp.com/webhook#key=value&key=value`

| Parameter | Key | Default | Range | Description |
|---|---|---|---|---|
| Connect Timeout | `ct` | 5000ms | 100-10000 | TCP connection timeout |
| Read Timeout | `rt` | 15000ms | 100-15000 | Time to wait for first response byte |
| Total Time | `tt` | 15000ms | 100-15000 | Total time for all retries |
| Retry Count | `rc` | 1 | 0-5 | Number of retry attempts |
| Retry Policy | `rp` | `ct` | `4xx`, `5xx`, `ct`, `rt`, `all` | What triggers a retry |
| Edge Location | `e` | `ashburn` | `ashburn`, `dublin`, `frankfurt`, `sao-paulo`, `singapore`, `sydney`, `tokyo`, `umatilla` | Egress edge |

**Examples:**

```text
# Retry up to 3 times on connection or read timeout
https://yourapp.com/sms#rc=3&rp=ct,rt

# Fast failover: 1s connect timeout, 2 retries
https://yourapp.com/voice#ct=1000&rc=2

# Rotate edge locations on retry
https://yourapp.com/status#e=ashburn,