error 11206: Twilio cannot parse your webhook's HTTP response

"""Report webhook endpoints returning HTTP that Twilio cannot parse (11206).

Read only. GET requests and nothing else: give this an API Key with read access
rather than the account auth token. The repair is printed, never performed,
because this script holds a credential to an account that can place calls and
spend money.
"""
import argparse
import datetime as dt
import logging
import os
import sys
from urllib.parse import urlsplit

import requests

logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
log = logging.getLogger("twilio_webhook_protocol_audit")

MONITOR = "https://monitor.twilio.com/v1"

PROTOCOL_VIOLATION = 11206

# Alerts are retained 30 days.
MAX_DAYS = 30


def code_of(alert):
    """Read error_code off an alert as an integer, or None.

    The Monitor API returns this as a string, and comparing it raw against
    11206 finds nothing at all.
    """
    raw = alert.get("error_code")
    if raw is None or raw == "":
        return None
    try:
        return int(raw)
    except (TypeError, ValueError):
        return None


def endpoint(url):
    """Host and path from a request URL, dropping the query string.

    Twilio appends its own parameters to the URL it fetches, so the query string
    differs on every alert and grouping on the whole URL would file each one
    under its own heading.
    """
    if not url:
        return ""
    parts = urlsplit(str(url).strip())
    host = (parts.hostname or "").lower()
    if not host:
        return ""
    return host + (parts.path or "/")


def header_lines(response_headers):
    """Normalise a fetched alert's response_headers into "Name: value" lines.

    The field's shape is not worth betting on: it arrives as a newline-joined
    string on some alerts and as a mapping on others, and a mapping can hold a
    list where a header repeats. Accepting all three costs six lines and saves a
    parser that silently returns nothing.
    """
    h = response_headers
    if not h:
        return []
    if isinstance(h, str):
        return [ln.strip() for ln in h.replace("\r\n", "\n").split("\n") if ln.strip()]
    if isinstance(h, dict):
        out = []
        for name, value in h.items():
            values = value if isinstance(value, (list, tuple)) else [value]
            out.extend("%s: %s" % (name, v) for v in values)
        return out
    if isinstance(h, (list, tuple)):
        return [str(x) for x in h if str(x).strip()]
    return []


def header_values(lines, name):
    """Every value for one header name, matched case-insensitively. Pure."""
    want = name.lower()
    out = []
    for line in lines:
        head, sep, rest = line.partition(":")
        if sep and head.strip().lower() == want:
            out.append(rest.strip())
    return out


def cookie_faults(value):
    """What is wrong with one Set-Cookie value. Pure, returns a sorted list.

    Both faults are emitted happily by most servers and refused by strict
    clients, which is the whole reason this failure reads as flakiness: it
    depends on the value, not on the code path.
    """
    faults = []
    raw = "" if value is None else str(value)
    if any(ord(c) < 0x20 or ord(c) == 0x7f for c in raw):
        faults.append("control-characters")
    pair = raw.split(";", 1)[0]
    if "=" not in pair or not pair.split("=", 1)[0].strip():
        faults.append("nameless")
    return sorted(faults)


def verdict(alert):
    """Classify one alert. Pure, so the two-stage read is testable offline.

    The first branch is the point of the note. A row from the alerts list has no
    response_headers key at all, and treating that absence as an empty header
    block would report every alert in the account as a scheme mismatch.

    Returns (state, detail).
    """
    if code_of(alert) != PROTOCOL_VIOLATION:
        return ("not-11206", "this alert is not an HTTP protocol violation")

    if "response_headers" not in alert:
        return ("unfetched",
                "this is a row from the alerts list. response_headers is "
                "populated only by GET /v1/Alerts/{Sid}, so nothing can be "
                "concluded until the alert is fetched on its own.")

    lines = header_lines(alert.get("response_headers"))
    cookies = header_values(lines, "set-cookie")
    broken = [(c, cookie_faults(c)) for c in cookies]
    broken = [(c, f) for c, f in broken if f]
    if broken:
        names = sorted({f for _c, faults in broken for f in faults})
        return ("malformed-cookie",
                "%d Set-Cookie value(s) a strict parser will refuse (%s). Most "
                "servers emit these without complaint, which is why your own "
                "logs show a clean 200." % (len(broken), ", ".join(names)))

    if not lines:
        return ("no-header-block",
                "the fetched alert carries no response headers, so the parse "
                "failed before a header block existed. The usual cause is a "
                "listener answering plain HTTP on a port the configured URL "
                "calls https.")

    return ("headers-parse",
            "%d header(s) read cleanly, so the violation is in the framing of "
            "the response itself: a truncated body, a Content-Length that does "
            "not match, or a chunked encoding that ended early." % len(lines))


def get(session, url, **params):
    r = session.get(url, params=params, timeout=30)
    if r.status_code in (401, 403):
        raise SystemExit("%d from Twilio: check TWILIO_ACCOUNT_SID and that the "
                         "API key belongs to that account with read access"
                         % r.status_code)
    r.raise_for_status()
    return r.json()


def list_alerts(session, since, limit, log_level="error"):
    """Page the Monitor alerts. next_page_url is absolute on this API."""
    url = MONITOR + "/Alerts"
    params = {"LogLevel": log_level, "StartDate": since, "PageSize": 1000}
    out = []
    while url and len(out) < limit:
        page = get(session, url, **params)
        out.extend(page.get("alerts", []))
        url = (page.get("meta") or {}).get("next_page_url")
        params = {}
    return out[:limit]


def fetch_alert(session, sid):
    """One alert on its own. The only place response_headers exists."""
    return get(session, "%s/Alerts/%s" % (MONITOR, sid))


def group(alerts):
    """Bucket the 11206s by endpoint, keeping the sids to sample from. Pure."""
    out = {}
    for a in alerts:
        if code_of(a) != PROTOCOL_VIOLATION:
            continue
        key = endpoint(a.get("request_url"))
        row = out.setdefault(key, {"alerts": 0, "sids": [], "url": ""})
        row["alerts"] += 1
        row["sids"].append(a.get("sid"))
        row["url"] = row["url"] or (a.get("request_url") or "")
    return out


def main():
    ap = argparse.ArgumentParser(description=__doc__)
    ap.add_argument("--days", type=int, default=7,
                    help="how far back to read alerts (Twilio keeps 30 days)")
    ap.add_argument("--max-alerts", type=int, default=10000,
                    help="stop paging alerts after this many")
    ap.add_argument("--sample", type=int, default=3,
                    help="alerts to fetch individually per endpoint; each one is "
                         "a request, and response_headers exists nowhere else")
    args = ap.parse_args()

    account = os.environ.get("TWILIO_ACCOUNT_SID")
    key = os.environ.get("TWILIO_API_KEY")
    secret = os.environ.get("TWILIO_API_SECRET")
    if not (account and key and secret):
        log.error("set TWILIO_ACCOUNT_SID, TWILIO_API_KEY and TWILIO_API_SECRET "
                  "(an API Key with read access, not the auth token)")
        return 2

    days = args.days
    if days > MAX_DAYS:
        log.warning("alerts are retained %d days; reading %d instead of %d",
                    MAX_DAYS, MAX_DAYS, days)
        days = MAX_DAYS

    session = requests.Session()
    session.auth = (key, secret)

    since = (dt.datetime.now(dt.timezone.utc)
             - dt.timedelta(days=days)).date().isoformat()

    alerts = list_alerts(session, since, args.max_alerts)
    rows = group(alerts)
    if not rows:
        log.info("no 11206 since %s across %d alert(s)", since, len(alerts))
        return 0

    log.info("%d endpoint(s) with 11206; fetching up to %d alert(s) each",
             len(rows), args.sample)

    bad = 0
    for key, row in sorted(rows.items()):
        bad += 1
        log.warning("%-17s %s  %d x 11206", "protocol-violation", key,
                    row["alerts"])
        log.warning("  sample %s", row["url"] or "(none)")
        for sid in row["sids"][:args.sample]:
            detailed = fetch_alert(session, sid)
            state, detail = verdict(detailed)
            log.warning("  %s %s  %s", sid, state, detail)
        log.warning("  repair: strip characters below 0x20 from cookie values "
                    "where they are set, drop cookies with an empty name, and "
                    "make the scheme in the configured URL match what the port "
                    "actually speaks.")

    log.info("%d endpoint(s) returning an unparseable HTTP response", bad)
    return 1 if bad else 0


if __name__ == "__main__":
    sys.exit(main())

/**
 * Report webhook endpoints returning HTTP that Twilio cannot parse (11206).
 *
 * Read only. GET requests and nothing else: give this an API Key with read
 * access rather than the account auth token. The repair is printed, never
 * performed.
 */
const MONITOR = 'https://monitor.twilio.com/v1';

const PROTOCOL_VIOLATION = 11206;

// Alerts are retained 30 days.
const MAX_DAYS = 30;

/** Read error_code off an alert as a number, or null. */
export function codeOf(alert) {
  const raw = alert.error_code;
  if (raw === null || raw === undefined || raw === '') return null;
  const n = Number(raw);
  return Number.isFinite(n) ? n : null;
}

/**
 * Host and path from a request URL, dropping the query string. Twilio appends
 * its own parameters, so grouping on the whole URL files every alert separately.
 */
export function endpoint(url) {
  if (!url) return '';
  let u;
  try {
    u = new URL(String(url).trim());
  } catch {
    return '';
  }
  const host = u.hostname.toLowerCase();
  if (!host) return '';
  return host + (u.pathname || '/');
}

/**
 * Normalise a fetched alert's response_headers into "Name: value" lines. The
 * field arrives as a string on some alerts and as a mapping on others, and a
 * mapping can hold a list where a header repeats.
 */
export function headerLines(responseHeaders) {
  const h = responseHeaders;
  if (!h) return [];
  if (typeof h === 'string') {
    return h.replace(/\r\n/g, '\n').split('\n')
      .map((ln) => ln.trim()).filter(Boolean);
  }
  if (Array.isArray(h)) return h.map(String).filter((x) => x.trim());
  if (typeof h === 'object') {
    const out = [];
    for (const [name, value] of Object.entries(h)) {
      for (const v of (Array.isArray(value) ? value : [value])) out.push(`${name}: ${v}`);
    }
    return out;
  }
  return [];
}

/** Every value for one header name, matched case-insensitively. Pure. */
export function headerValues(lines, name) {
  const want = name.toLowerCase();
  const out = [];
  for (const line of lines) {
    const i = line.indexOf(':');
    if (i > -1 && line.slice(0, i).trim().toLowerCase() === want) {
      out.push(line.slice(i + 1).trim());
    }
  }
  return out;
}

/**
 * What is wrong with one Set-Cookie value. Pure, returns a sorted list. Both
 * faults are emitted happily by most servers and refused by strict clients.
 */
export function cookieFaults(value) {
  const faults = [];
  const raw = value === null || value === undefined ? '' : String(value);
  if ([...raw].some((c) => c.charCodeAt(0) < 0x20 || c.charCodeAt(0) === 0x7f)) {
    faults.push('control-characters');
  }
  const pair = raw.split(';')[0];
  if (!pair.includes('=') || !pair.split('=')[0].trim()) faults.push('nameless');
  return faults.sort();
}

/**
 * Classify one alert. Pure, so the two-stage read is testable offline. The
 * first branch is the point: a row from the list has no response_headers key,
 * and treating that absence as an empty header block would misreport everything.
 * Returns [state, detail].
 */
export function verdict(alert) {
  if (codeOf(alert) !== PROTOCOL_VIOLATION) {
    return ['not-11206', 'this alert is not an HTTP protocol violation'];
  }

  if (!Object.prototype.hasOwnProperty.call(alert, 'response_headers')) {
    return ['unfetched',
      'this is a row from the alerts list. response_headers is populated only ' +
      'by GET /v1/Alerts/{Sid}, so nothing can be concluded until the alert ' +
      'is fetched on its own.'];
  }

  const lines = headerLines(alert.response_headers);
  const broken = headerValues(lines, 'set-cookie')
    .map((c) => [c, cookieFaults(c)]).filter(([, f]) => f.length);
  if (broken.length) {
    const names = [...new Set(broken.flatMap(([, f]) => f))].sort();
    return ['malformed-cookie',
      `${broken.length} Set-Cookie value(s) a strict parser will refuse ` +
      `(${names.join(', ')}). Most servers emit these without complaint, ` +
      'which is why your own logs show a clean 200.'];
  }

  if (lines.length === 0) {
    return ['no-header-block',
      'the fetched alert carries no response headers, so the parse failed ' +
      'before a header block existed. The usual cause is a listener answering ' +
      'plain HTTP on a port the configured URL calls https.'];
  }

  return ['headers-parse',
    `${lines.length} header(s) read cleanly, so the violation is in the ` +
    'framing of the response itself: a truncated body, a Content-Length that ' +
    'does not match, or a chunked encoding that ended early.'];
}

/** Bucket the 11206s by endpoint, keeping the sids to sample from. Pure. */
export function group(alerts) {
  const out = new Map();
  for (const a of alerts) {
    if (codeOf(a) !== PROTOCOL_VIOLATION) continue;
    const key = endpoint(a.request_url);
    if (!out.has(key)) out.set(key, { alerts: 0, sids: [], url: '' });
    const row = out.get(key);
    row.alerts += 1;
    row.sids.push(a.sid);
    row.url = row.url || (a.request_url ?? '');
  }
  return out;
}

function authHeader(key, secret) {
  return `Basic ${Buffer.from(`${key}:${secret}`).toString('base64')}`;
}

async function get(auth, url, params = {}) {
  const u = new URL(url);
  for (const [k, v] of Object.entries(params)) u.searchParams.set(k, v);
  const res = await fetch(u, { headers: { Authorization: auth } });
  if (res.status === 401 || res.status === 403) {
    throw new Error(`${res.status} from Twilio: check TWILIO_ACCOUNT_SID and ` +
                    'that the API key belongs to that account with read access');
  }
  if (!res.ok) throw new Error(`${res.status} from ${u.pathname}`);
  return res.json();
}

export async function listAlerts(auth, since, limit = 10000, logLevel = 'error') {
  let url = `${MONITOR}/Alerts`;
  let params = { LogLevel: logLevel, StartDate: since, PageSize: 1000 };
  const out = [];
  while (url && out.length < limit) {
    const page = await get(auth, url, params);
    out.push(...(page.alerts ?? []));
    url = page.meta?.next_page_url ?? null;
    params = {};
  }
  return out.slice(0, limit);
}

async function main() {
  const account = process.env.TWILIO_ACCOUNT_SID;
  const key = process.env.TWILIO_API_KEY;
  const secret = process.env.TWILIO_API_SECRET;
  if (!account || !key || !secret) {
    console.error('set TWILIO_ACCOUNT_SID, TWILIO_API_KEY and TWILIO_API_SECRET ' +
                  '(an API Key with read access, not the auth token)');
    process.exitCode = 2;
    return;
  }
  const auth = authHeader(key, secret);

  const dayArg = process.argv.indexOf('--days');
  let days = dayArg > -1 ? Number(process.argv[dayArg + 1]) : 7;
  if (!Number.isFinite(days) || days < 1) days = 7;
  if (days > MAX_DAYS) {
    console.warn(`alerts are retained ${MAX_DAYS} days; reading ${MAX_DAYS}`);
    days = MAX_DAYS;
  }
  const sampleArg = process.argv.indexOf('--sample');
  const sample = sampleArg > -1 ? Number(process.argv[sampleArg + 1]) || 3 : 3;

  const since = new Date(Date.now() - days * 86400_000).toISOString().slice(0, 10);

  const alerts = await listAlerts(auth, since);
  const rows = group(alerts);
  if (rows.size === 0) {
    console.log(`no 11206 since ${since} across ${alerts.length} alert(s)`);
    return;
  }

  console.log(`${rows.size} endpoint(s) with 11206; fetching up to ${sample} each`);

  let bad = 0;
  for (const key of [...rows.keys()].sort()) {
    const row = rows.get(key);
    bad += 1;
    console.warn(`${'protocol-violation'.padEnd(17)} ${key}  ${row.alerts} x 11206`);
    console.warn(`  sample ${row.url || '(none)'}`);
    for (const sid of row.sids.slice(0, sample)) {
      const detailed = await get(auth, `${MONITOR}/Alerts/${sid}`);
      const [state, detail] = verdict(detailed);
      console.warn(`  ${sid} ${state}  ${detail}`);
    }
    console.warn('  repair: strip characters below 0x20 from cookie values ' +
      'where they are set, drop cookies with an empty name, and make the ' +
      'scheme in the configured URL match what the port actually speaks.');
  }

  console.log(`${bad} endpoint(s) returning an unparseable HTTP response`);
  process.exitCode = bad ? 1 : 0;
}

// Only run when invoked directly. The test file imports this module, and without
// the guard main() would run there too, fail on the missing credentials and set a
// non-zero exit code that fails the whole test file even as every test passes.
if (import.meta.url === `file://${process.argv[1]}`) {
  main().catch((err) => { console.error(err.message); process.exitCode = 2; });
}

from twilio_webhook_protocol_audit import (
    cookie_faults, endpoint, group, header_lines, header_values, verdict)


def listed(sid="NO1", url="https://hooks.example.com/voice?AccountSid=AC1"):
    """A row exactly as the alerts list returns it: no response_headers key."""
    return {"sid": sid, "request_url": url, "error_code": "11206",
            "date_generated": "2026-05-05T14:08:00Z"}


def fetched(headers):
    d = listed()
    d["response_headers"] = headers
    return d


def test_a_list_row_is_reported_as_unfetched_not_as_an_empty_header_block():
    # The whole trap of this note. response_headers exists only on the
    # single-alert fetch, and absence is not emptiness.
    state, detail = verdict(listed())
    assert state == "unfetched"
    assert "/v1/Alerts/" in detail


def test_endpoint_drops_the_query_twilio_appends():
    assert endpoint("https://Hooks.Example.com/voice?AccountSid=AC1") == \
        "hooks.example.com/voice"
    assert endpoint("https://hooks.example.com") == "hooks.example.com/"
    assert endpoint("") == ""


def test_header_lines_accepts_a_string_a_mapping_and_a_repeat():
    assert header_lines("Content-Type: text/xml\r\nServer: nginx") == \
        ["Content-Type: text/xml", "Server: nginx"]
    assert header_lines({"Set-Cookie": ["a=1", "b=2"]}) == \
        ["Set-Cookie: a=1", "Set-Cookie: b=2"]
    assert header_lines(None) == []


def test_header_values_matches_case_insensitively():
    lines = ["set-cookie: a=1", "Set-Cookie: b=2", "Server: nginx"]
    assert header_values(lines, "Set-Cookie") == ["a=1", "b=2"]


def test_cookie_faults_finds_a_control_character_and_an_empty_name():
    assert cookie_faults("sid=abc123; Path=/") == []
    assert cookie_faults("sid=ab\ncd; Path=/") == ["control-characters"]
    assert cookie_faults("=abc123; Path=/") == ["nameless"]
    assert cookie_faults("=ab\tcd") == ["control-characters", "nameless"]


def test_a_malformed_cookie_is_named_in_the_verdict():
    state, detail = verdict(fetched({"Set-Cookie": ["ok=1", "=orphan"]}))
    assert state == "malformed-cookie"
    assert "nameless" in detail


def test_an_empty_header_block_on_a_fetched_alert_is_a_scheme_mismatch():
    state, detail = verdict(fetched(""))
    assert state == "no-header-block"
    assert "plain HTTP" in detail


def test_clean_headers_move_the_diagnosis_into_the_body_framing():
    state, detail = verdict(fetched("Content-Type: text/xml\nSet-Cookie: sid=1"))
    assert state == "headers-parse"
    assert "Content-Length" in detail


def test_another_error_code_is_not_this_failure():
    other = fetched("Content-Type: text/xml")
    other["error_code"] = "11200"
    assert verdict(other)[0] == "not-11206"


def test_group_buckets_by_endpoint_and_keeps_the_sids():
    rows = group([listed("A1"), listed("A2"),
                  listed("A3", "https://hooks.example.com/sms?x=1")])
    assert sorted(rows) == ["hooks.example.com/sms", "hooks.example.com/voice"]
    assert rows["hooks.example.com/voice"]["sids"] == ["A1", "A2"]

import { test } from 'node:test';
import assert from 'node:assert/strict';
import {
  cookieFaults, endpoint, group, headerLines, headerValues, verdict,
} from './twilio-webhook-protocol-audit.mjs';

// A row exactly as the alerts list returns it: no response_headers key.
const listed = (sid = 'NO1', url = 'https://hooks.example.com/voice?AccountSid=AC1') => ({
  sid, request_url: url, error_code: '11206', date_generated: '2026-05-05T14:08:00Z',
});

const fetched = (headers) => ({ ...listed(), response_headers: headers });

test('a list row is reported as unfetched not as an empty header block', () => {
  const [state, detail] = verdict(listed());
  assert.equal(state, 'unfetched');
  assert.match(detail, /\/v1\/Alerts\//);
});

test('endpoint drops the query Twilio appends', () => {
  assert.equal(endpoint('https://Hooks.Example.com/voice?AccountSid=AC1'),
    'hooks.example.com/voice');
  assert.equal(endpoint('https://hooks.example.com'), 'hooks.example.com/');
  assert.equal(endpoint(''), '');
});

test('headerLines accepts a string, a mapping and a repeat', () => {
  assert.deepEqual(headerLines('Content-Type: text/xml\r\nServer: nginx'),
    ['Content-Type: text/xml', 'Server: nginx']);
  assert.deepEqual(headerLines({ 'Set-Cookie': ['a=1', 'b=2'] }),
    ['Set-Cookie: a=1', 'Set-Cookie: b=2']);
  assert.deepEqual(headerLines(null), []);
});

test('headerValues matches case insensitively', () => {
  const lines = ['set-cookie: a=1', 'Set-Cookie: b=2', 'Server: nginx'];
  assert.deepEqual(headerValues(lines, 'Set-Cookie'), ['a=1', 'b=2']);
});

test('cookieFaults finds a control character and an empty name', () => {
  assert.deepEqual(cookieFaults('sid=abc123; Path=/'), []);
  assert.deepEqual(cookieFaults('sid=ab\ncd; Path=/'), ['control-characters']);
  assert.deepEqual(cookieFaults('=abc123; Path=/'), ['nameless']);
  assert.deepEqual(cookieFaults('=ab\tcd'), ['control-characters', 'nameless']);
});

test('a malformed cookie is named in the verdict', () => {
  const [state, detail] = verdict(fetched({ 'Set-Cookie': ['ok=1', '=orphan'] }));
  assert.equal(state, 'malformed-cookie');
  assert.match(detail, /nameless/);
});

test('an empty header block on a fetched alert is a scheme mismatch', () => {
  const [state, detail] = verdict(fetched(''));
  assert.equal(state, 'no-header-block');
  assert.match(detail, /plain HTTP/);
});

test('clean headers move the diagnosis into the body framing', () => {
  const [state, detail] = verdict(fetched('Content-Type: text/xml\nSet-Cookie: sid=1'));
  assert.equal(state, 'headers-parse');
  assert.match(detail, /Content-Length/);
});

test('another error code is not this failure', () => {
  const other = fetched('Content-Type: text/xml');
  other.error_code = '11200';
  assert.equal(verdict(other)[0], 'not-11206');
});

test('group buckets by endpoint and keeps the sids', () => {
  const rows = group([listed('A1'), listed('A2'),
    listed('A3', 'https://hooks.example.com/sms?x=1')]);
  assert.deepEqual([...rows.keys()].sort(),
    ['hooks.example.com/sms', 'hooks.example.com/voice']);
  assert.deepEqual(rows.get('hooks.example.com/voice').sids, ['A1', 'A2']);
});