an endpoint subscribes to every event and floods the handler

"""Report Stripe webhook endpoints subscribed to far more events than they handle.

Read only. Two GETs, no writes: give this a RESTRICTED key with read access to
Webhook Endpoints and Events. The repair is printed, never performed, because
this script holds a credential to a live payments account.
"""
import argparse
import logging
import os
import sys

import requests

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

API = "https://api.stripe.com/v1"

# Above this an explicit list is a wildcard somebody typed out by hand.
WIDE = 40


def verdict(enabled_events, fired_types):
    """Classify one endpoint's subscription. Pure, so the rules can be tested.

    `enabled_events` is the endpoint's array; `fired_types` is the set of event
    types actually seen in the retained window. Returns (state, detail).
    """
    events = list(enabled_events or [])
    if not events:
        return ("empty", "no enabled_events at all: this endpoint receives nothing")
    if "*" in events:
        return ("wildcard",
                "subscribed to every event type. %d distinct type(s) fired in the "
                "retained window, and all of them are being delivered."
                % len(set(fired_types or [])))
    if len(events) > WIDE:
        return ("overbroad",
                "%d explicit types subscribed. That is a wildcard written out by "
                "hand and carries the same load." % len(events))
    unused = sorted(e for e in set(events) if e not in set(fired_types or []))
    if unused:
        return ("padded",
                "%d of %d subscribed type(s) never fired in the retained window: %s"
                % (len(unused), len(set(events)), ", ".join(unused[:5])))
    return ("focused", "%d type(s), all seen firing" % len(set(events)))


def get(session, path, **params):
    r = session.get(API + path, params=params, timeout=30)
    if r.status_code == 401:
        raise SystemExit("401 from Stripe: the key is wrong, or is for the other mode")
    r.raise_for_status()
    return r.json()


def fired_types(session, limit):
    """Distinct event types seen in the retained window, with counts."""
    counts = {}
    total = 0
    params = {"limit": 100}
    while True:
        page = get(session, "/events", **params)
        data = page.get("data", [])
        for ev in data:
            total += 1
            t = ev.get("type")
            counts[t] = counts.get(t, 0) + 1
        if not data or not page.get("has_more") or total >= limit:
            break
        params["starting_after"] = data[-1]["id"]
    return counts


def main():
    ap = argparse.ArgumentParser(description=__doc__)
    ap.add_argument("--max-events", type=int, default=2000,
                    help="stop sampling event types after this many events")
    args = ap.parse_args()

    key = os.environ.get("STRIPE_API_KEY")
    if not key:
        log.error("set STRIPE_API_KEY (use a restricted, read-only key)")
        return 2

    s = requests.Session()
    s.headers.update({"Authorization": "Bearer " + key})

    endpoints = get(s, "/webhook_endpoints", limit=100).get("data", [])
    if not endpoints:
        log.info("no webhook endpoints configured for this key's mode")
        return 0

    counts = fired_types(s, args.max_events)
    log.info("sampled %d event(s) across %d distinct type(s)",
             sum(counts.values()), len(counts))

    bad = 0
    for ep in endpoints:
        state, detail = verdict(ep.get("enabled_events"), counts.keys())
        line = "%-10s %s  %s" % (state, ep.get("url", "?"), detail)
        if state == "focused":
            log.info(line)
            continue
        bad += 1
        log.warning(line)
        if state in ("wildcard", "overbroad", "padded"):
            top = sorted(counts.items(), key=lambda kv: -kv[1])[:8]
            log.warning("  busiest types seen: %s",
                        ", ".join("%s x%d" % (t, n) for t, n in top))
            log.warning("  repair: POST %s/webhook_endpoints/%s "
                        "-d enabled_events[]=<type> ... (one per branch in your handler)",
                        API, ep["id"])

    log.info("%d endpoint(s), %d needing attention", len(endpoints), bad)
    return 1 if bad else 0


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

/**
 * Report Stripe webhook endpoints subscribed to far more events than they handle.
 *
 * Read only. Two GETs, no writes: give this a RESTRICTED key with read access to
 * Webhook Endpoints and Events. The repair is printed, never performed.
 */
const API = 'https://api.stripe.com/v1';

// Above this an explicit list is a wildcard somebody typed out by hand.
const WIDE = 40;

/**
 * Classify one endpoint's subscription. Pure, so the rules can be tested.
 * `firedTypes` is the set of event types actually seen in the retained window.
 */
export function verdict(enabledEvents, firedTypes) {
  const events = [...(enabledEvents ?? [])];
  const fired = new Set(firedTypes ?? []);
  if (events.length === 0) {
    return ['empty', 'no enabled_events at all: this endpoint receives nothing'];
  }
  if (events.includes('*')) {
    return ['wildcard',
      `subscribed to every event type. ${fired.size} distinct type(s) fired in ` +
      'the retained window, and all of them are being delivered.'];
  }
  if (events.length > WIDE) {
    return ['overbroad',
      `${events.length} explicit types subscribed. That is a wildcard written ` +
      'out by hand and carries the same load.'];
  }
  const distinct = new Set(events);
  const unused = [...distinct].filter((e) => !fired.has(e)).sort();
  if (unused.length > 0) {
    return ['padded',
      `${unused.length} of ${distinct.size} subscribed type(s) never fired in ` +
      `the retained window: ${unused.slice(0, 5).join(', ')}`];
  }
  return ['focused', `${distinct.size} type(s), all seen firing`];
}

async function get(key, path, params = {}) {
  const url = new URL(API + path);
  for (const [k, v] of Object.entries(params)) url.searchParams.set(k, v);
  const res = await fetch(url, { headers: { Authorization: `Bearer ${key}` } });
  if (res.status === 401) {
    throw new Error('401 from Stripe: the key is wrong, or is for the other mode');
  }
  if (!res.ok) throw new Error(`${res.status} from ${url.pathname}`);
  return res.json();
}

export async function firedTypes(key, limit = 2000) {
  const counts = new Map();
  let total = 0;
  const params = { limit: 100 };
  for (;;) {
    const page = await get(key, '/events', params);
    const data = page.data ?? [];
    for (const ev of data) {
      total += 1;
      counts.set(ev.type, (counts.get(ev.type) ?? 0) + 1);
    }
    if (data.length === 0 || !page.has_more || total >= limit) break;
    params.starting_after = data[data.length - 1].id;
  }
  return counts;
}

async function main() {
  const key = process.env.STRIPE_API_KEY;
  if (!key) {
    console.error('set STRIPE_API_KEY (use a restricted, read-only key)');
    process.exitCode = 2;
    return;
  }

  const { data: endpoints = [] } = await get(key, '/webhook_endpoints', { limit: 100 });
  if (endpoints.length === 0) {
    console.log("no webhook endpoints configured for this key's mode");
    return;
  }

  const counts = await firedTypes(key);
  const sampled = [...counts.values()].reduce((a, b) => a + b, 0);
  console.log(`sampled ${sampled} event(s) across ${counts.size} distinct type(s)`);

  let bad = 0;
  for (const ep of endpoints) {
    const [state, detail] = verdict(ep.enabled_events, counts.keys());
    const line = `${state.padEnd(10)} ${ep.url ?? '?'}  ${detail}`;
    if (state === 'focused') { console.log(line); continue; }
    bad += 1;
    console.warn(line);
    const top = [...counts.entries()].sort((a, b) => b[1] - a[1]).slice(0, 8);
    console.warn(`  busiest types seen: ${top.map(([t, n]) => `${t} x${n}`).join(', ')}`);
    console.warn(`  repair: POST ${API}/webhook_endpoints/${ep.id} ` +
                 '-d enabled_events[]=<type> ... (one per branch in your handler)');
  }

  console.log(`${endpoints.length} endpoint(s), ${bad} needing attention`);
  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 key, 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 stripe_wildcard_events import verdict

FIRED = ["payment_intent.succeeded", "charge.refunded", "invoice.paid"]


def test_literal_star_is_a_wildcard():
    state, detail = verdict(["*"], FIRED)
    assert state == "wildcard"
    assert "3" in detail


def test_a_long_explicit_list_is_a_wildcard_typed_out():
    # The case a naive check misses: no star anywhere, same load.
    state, _ = verdict(["evt.%d" % i for i in range(60)], FIRED)
    assert state == "overbroad"


def test_subscribed_types_that_never_fire_are_reported():
    state, detail = verdict(["payment_intent.succeeded", "issuing_card.created"],
                            FIRED)
    assert state == "padded"
    assert "issuing_card.created" in detail


def test_a_list_matching_real_traffic_is_focused():
    state, _ = verdict(FIRED, FIRED)
    assert state == "focused"


def test_empty_enabled_events_is_not_focused():
    state, _ = verdict([], FIRED)
    assert state == "empty"

import { test } from 'node:test';
import assert from 'node:assert/strict';
import { verdict } from './stripe-wildcard-events.mjs';

const FIRED = ['payment_intent.succeeded', 'charge.refunded', 'invoice.paid'];

test('literal star is a wildcard', () => {
  const [state, detail] = verdict(['*'], FIRED);
  assert.equal(state, 'wildcard');
  assert.match(detail, /3 distinct/);
});

test('a long explicit list is a wildcard typed out', () => {
  const many = Array.from({ length: 60 }, (_, i) => `evt.${i}`);
  assert.equal(verdict(many, FIRED)[0], 'overbroad');
});

test('subscribed types that never fire are reported', () => {
  const [state, detail] = verdict(
    ['payment_intent.succeeded', 'issuing_card.created'], FIRED);
  assert.equal(state, 'padded');
  assert.match(detail, /issuing_card\.created/);
});

test('a list matching real traffic is focused', () => {
  assert.equal(verdict(FIRED, FIRED)[0], 'focused');
});

test('empty enabled_events is not focused', () => {
  assert.equal(verdict([], FIRED)[0], 'empty');
});