event types are firing that no endpoint subscribes to

"""Report Stripe event types that fire but reach no webhook endpoint.

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_unsubscribed_events")

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


def classify(event_type, count, subscribed):
    """Classify one fired event type against the subscription union.

    Pure, so the rules can be tested without a network. `subscribed` is the union
    of enabled_events across every endpoint. Returns (state, detail).
    """
    events = set(subscribed or [])
    if count <= 0:
        return ("unseen", "%s did not fire in the retained window" % event_type)
    if "*" in events:
        return ("wildcard",
                "%s is delivered by a wildcard subscription, along with every "
                "other type the account generates." % event_type)
    if event_type in events:
        return ("covered", "%s is subscribed on at least one endpoint" % event_type)

    namespace = event_type.split(".")[0]
    siblings = sorted(e for e in events if e.split(".")[0] == namespace)
    if siblings:
        return ("near-miss",
                "%s fired %d time(s) and is not subscribed, though %s is. "
                "enabled_events matches type names exactly: only the literal * "
                "is a wildcard, so a namespace is never covered by a sibling."
                % (event_type, count, siblings[0]))
    return ("missed",
            "%s fired %d time(s) and reached no endpoint. Nothing in the %s "
            "namespace is subscribed anywhere on this account."
            % (event_type, count, namespace))


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 subscribed_union(session):
    """Every event type any endpoint on this account asks for."""
    union = set()
    for ep in get(session, "/webhook_endpoints", limit=100).get("data", []):
        union.update(ep.get("enabled_events") or [])
    return union


def fired_counts(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
            counts[ev.get("type")] = counts.get(ev.get("type"), 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 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})

    union = subscribed_union(s)
    if not union:
        log.warning("no endpoint subscribes to anything in this mode: "
                    "every event below is undelivered")

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

    gaps = 0
    for event_type, count in sorted(counts.items(), key=lambda kv: -kv[1]):
        state, detail = classify(event_type, count, union)
        if state in ("covered", "wildcard", "unseen"):
            continue
        gaps += 1
        log.warning("%-9s %s", state, detail)

    if gaps:
        log.warning("repair: add the types your handler branches on to an existing "
                    "endpoint's enabled_events[] at %s/webhook_endpoints/{id}. "
                    "Adding * instead trades this for a flooded handler", API)
    log.info("%d type(s) fired, %d unsubscribed", len(counts), gaps)
    return 1 if gaps else 0


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

/**
 * Report Stripe event types that fire but reach no webhook endpoint.
 *
 * 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';

/**
 * Classify one fired event type against the subscription union. Pure, so the
 * rules can be tested without a network.
 */
export function classify(eventType, count, subscribed) {
  const events = new Set(subscribed ?? []);
  if (count <= 0) return ['unseen', `${eventType} did not fire in the retained window`];
  if (events.has('*')) {
    return ['wildcard',
      `${eventType} is delivered by a wildcard subscription, along with every ` +
      'other type the account generates.'];
  }
  if (events.has(eventType)) {
    return ['covered', `${eventType} is subscribed on at least one endpoint`];
  }

  const namespace = eventType.split('.')[0];
  const siblings = [...events].filter((e) => e.split('.')[0] === namespace).sort();
  if (siblings.length > 0) {
    return ['near-miss',
      `${eventType} fired ${count} time(s) and is not subscribed, though ` +
      `${siblings[0]} is. enabled_events matches type names exactly: only the ` +
      'literal * is a wildcard, so a namespace is never covered by a sibling.'];
  }
  return ['missed',
    `${eventType} fired ${count} time(s) and reached no endpoint. Nothing in ` +
    `the ${namespace} namespace is subscribed anywhere on this account.`];
}

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 subscribedUnion(key) {
  const union = new Set();
  const { data = [] } = await get(key, '/webhook_endpoints', { limit: 100 });
  for (const ep of data) for (const t of ep.enabled_events ?? []) union.add(t);
  return union;
}

export async function firedCounts(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 union = await subscribedUnion(key);
  if (union.size === 0) {
    console.warn('no endpoint subscribes to anything in this mode: ' +
                 'every event below is undelivered');
  }

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

  let gaps = 0;
  for (const [eventType, count] of [...counts.entries()].sort((a, b) => b[1] - a[1])) {
    const [state, detail] = classify(eventType, count, union);
    if (state === 'covered' || state === 'wildcard' || state === 'unseen') continue;
    gaps += 1;
    console.warn(`${state.padEnd(9)} ${detail}`);
  }

  if (gaps > 0) {
    console.warn('repair: add the types your handler branches on to an existing ' +
                 `endpoint's enabled_events[] at ${API}/webhook_endpoints/{id}. ` +
                 'Adding * instead trades this for a flooded handler');
  }
  console.log(`${counts.size} type(s) fired, ${gaps} unsubscribed`);
  process.exitCode = gaps ? 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_unsubscribed_events import classify

SUBSCRIBED = ["payment_intent.succeeded", "invoice.paid"]


def test_a_subscribed_type_is_covered():
    state, _ = classify("invoice.paid", 12, SUBSCRIBED)
    assert state == "covered"


def test_a_type_with_no_sibling_subscribed_is_missed():
    state, detail = classify("charge.dispute.created", 7, SUBSCRIBED)
    assert state == "missed"
    assert "7 time(s)" in detail
    assert "charge" in detail


def test_a_sibling_subscription_does_not_cover_the_type():
    # payment_intent.succeeded is subscribed; the failure is not implied by it.
    state, detail = classify("payment_intent.payment_failed", 31, SUBSCRIBED)
    assert state == "near-miss"
    assert "payment_intent.succeeded" in detail


def test_a_namespace_pattern_is_not_a_subscription():
    # Only the literal * is a wildcard. "payment_intent.*" matches nothing.
    state, _ = classify("payment_intent.succeeded", 5, ["payment_intent.*"])
    assert state != "covered"
    assert state == "near-miss"


def test_a_wildcard_covers_everything():
    state, _ = classify("radar.early_fraud_warning.created", 2, ["*"])
    assert state == "wildcard"


def test_a_type_that_never_fired_is_not_a_gap():
    state, _ = classify("invoice.paid", 0, [])
    assert state == "unseen"

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

const SUBSCRIBED = ['payment_intent.succeeded', 'invoice.paid'];

test('a subscribed type is covered', () => {
  assert.equal(classify('invoice.paid', 12, SUBSCRIBED)[0], 'covered');
});

test('a type with no sibling subscribed is missed', () => {
  const [state, detail] = classify('charge.dispute.created', 7, SUBSCRIBED);
  assert.equal(state, 'missed');
  assert.match(detail, /7 time\(s\)/);
});

test('a sibling subscription does not cover the type', () => {
  const [state, detail] = classify('payment_intent.payment_failed', 31, SUBSCRIBED);
  assert.equal(state, 'near-miss');
  assert.match(detail, /payment_intent\.succeeded/);
});

test('a namespace pattern is not a subscription', () => {
  const [state] = classify('payment_intent.succeeded', 5, ['payment_intent.*']);
  assert.notEqual(state, 'covered');
  assert.equal(state, 'near-miss');
});

test('a wildcard covers everything', () => {
  assert.equal(classify('radar.early_fraud_warning.created', 2, ['*'])[0], 'wildcard');
});

test('a type that never fired is not a gap', () => {
  assert.equal(classify('invoice.paid', 0, [])[0], 'unseen');
});