enabled_events lists event types that are dead or rejected

"""Report Stripe webhook subscriptions to event types that are dead or rejected.

Read only. Two GETs and 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_dead_event_types")

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

# The Sources API families. These stay configurable but stop occurring once the
# integration moves to PaymentIntents and PaymentMethods.
LEGACY_PREFIXES = ("source.", "customer.source.")

# Types the API no longer accepts on an update, so one of these poisons every
# future change to the endpoint. Keep in step with the enabled_events enum in
# the create-endpoint reference; this is the short list seen in the wild.
REJECTED = frozenset({"invoiceitem.updated"})


def verdict(event_type, fired):
    """Classify one subscribed event type. Pure, so the rules can be tested.

    `fired` is the set of event types actually seen in the retained window.
    Returns (state, detail).
    """
    if event_type == "*":
        return ("wildcard",
                "subscribed to every type: there is no list here to diff")
    seen = set(fired or [])
    if event_type in REJECTED:
        return ("rejected",
                "the API no longer accepts this type. The next update to this "
                "endpoint fails on it, whatever the update was for.")
    if event_type.startswith(LEGACY_PREFIXES):
        if event_type in seen:
            return ("legacy",
                    "a Sources API type that is still firing: something in the "
                    "integration still creates Sources")
        return ("dead",
                "a Sources API type with no occurrences in the retained window. "
                "It does not fire for a PaymentMethod integration, so any "
                "handler branch behind it is dead code.")
    if event_type in seen:
        return ("live", "seen firing in the retained window")
    return ("quiet",
            "no occurrences in the retained window. That is low volume, not "
            "proof of decay: disputes and failures are supposed to be rare.")


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):
    """The set of event types seen in the retained window."""
    seen = set()
    total = 0
    params = {"limit": 100}
    while True:
        page = get(session, "/events", **params)
        data = page.get("data", [])
        for ev in data:
            total += 1
            seen.add(ev.get("type"))
        if not data or not page.get("has_more") or total >= limit:
            break
        params["starting_after"] = data[-1]["id"]
    return seen, total


def main():
    ap = argparse.ArgumentParser(description=__doc__)
    ap.add_argument("--max-events", type=int, default=5000,
                    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})

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

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

    bad = 0
    for ep in eps:
        keep = []
        drop = []
        for t in ep.get("enabled_events") or []:
            state, detail = verdict(t, seen)
            line = "%-9s %-32s %s" % (state, t, detail)
            if state in ("dead", "rejected"):
                bad += 1
                drop.append(t)
                log.warning("%s  %s", ep.get("url", "?"), line)
            else:
                keep.append(t)
                log.info("%s  %s", ep.get("url", "?"), line)
        if drop:
            log.warning("  enabled_events is replaced wholesale on update, so "
                        "re-send the full corrected list:")
            log.warning("  repair: POST %s/webhook_endpoints/%s %s",
                        API, ep["id"],
                        " ".join("-d enabled_events[]=%s" % t for t in keep[:6])
                        + (" ..." if len(keep) > 6 else ""))
            log.warning("  dropping: %s", ", ".join(drop))

    log.info("%d endpoint(s), %d dead or rejected subscription(s)", len(eps), bad)
    return 1 if bad else 0


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

/**
 * Report Stripe webhook subscriptions to event types that are dead or rejected.
 *
 * Read only. Two GETs and 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';

// The Sources API families. These stay configurable but stop occurring once the
// integration moves to PaymentIntents and PaymentMethods.
const LEGACY_PREFIXES = ['source.', 'customer.source.'];

// Types the API no longer accepts on an update, so one of these poisons every
// future change to the endpoint.
export const REJECTED = new Set(['invoiceitem.updated']);

/**
 * Classify one subscribed event type. Pure, so the rules can be tested.
 * `fired` is the set of event types actually seen in the retained window.
 */
export function verdict(eventType, fired) {
  if (eventType === '*') {
    return ['wildcard', 'subscribed to every type: there is no list here to diff'];
  }
  const seen = new Set(fired ?? []);
  if (REJECTED.has(eventType)) {
    return ['rejected',
      'the API no longer accepts this type. The next update to this endpoint ' +
      'fails on it, whatever the update was for.'];
  }
  if (LEGACY_PREFIXES.some((p) => eventType.startsWith(p))) {
    if (seen.has(eventType)) {
      return ['legacy',
        'a Sources API type that is still firing: something in the integration ' +
        'still creates Sources'];
    }
    return ['dead',
      'a Sources API type with no occurrences in the retained window. It does ' +
      'not fire for a PaymentMethod integration, so any handler branch behind ' +
      'it is dead code.'];
  }
  if (seen.has(eventType)) return ['live', 'seen firing in the retained window'];
  return ['quiet',
    'no occurrences in the retained window. That is low volume, not proof of ' +
    'decay: disputes and failures are supposed to be rare.'];
}

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 = 5000) {
  const seen = new Set();
  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; seen.add(ev.type); }
    if (data.length === 0 || !page.has_more || total >= limit) break;
    params.starting_after = data[data.length - 1].id;
  }
  return { seen, total };
}

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: eps = [] } = await get(key, '/webhook_endpoints', { limit: 100 });
  if (eps.length === 0) {
    console.log("no webhook endpoints configured for this key's mode");
    return;
  }

  const { seen, total } = await firedTypes(key);
  console.log(`sampled ${total} event(s) across ${seen.size} distinct type(s)`);

  let bad = 0;
  for (const ep of eps) {
    const keep = [];
    const drop = [];
    for (const t of ep.enabled_events ?? []) {
      const [state, detail] = verdict(t, seen);
      const line = `${state.padEnd(9)} ${t.padEnd(32)} ${detail}`;
      if (state === 'dead' || state === 'rejected') {
        bad += 1;
        drop.push(t);
        console.warn(`${ep.url ?? '?'}  ${line}`);
      } else {
        keep.push(t);
        console.log(`${ep.url ?? '?'}  ${line}`);
      }
    }
    if (drop.length) {
      console.warn('  enabled_events is replaced wholesale on update, so ' +
                   're-send the full corrected list:');
      const args = keep.slice(0, 6).map((t) => `-d enabled_events[]=${t}`).join(' ');
      console.warn(`  repair: POST ${API}/webhook_endpoints/${ep.id} ${args}` +
                   (keep.length > 6 ? ' ...' : ''));
      console.warn(`  dropping: ${drop.join(', ')}`);
    }
  }

  console.log(`${eps.length} endpoint(s), ${bad} dead or rejected subscription(s)`);
  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_dead_event_types import verdict

FIRED = {"payment_intent.succeeded", "invoice.paid", "customer.source.expiring"}


def test_a_removed_type_is_rejected():
    state, detail = verdict("invoiceitem.updated", FIRED)
    assert state == "rejected"
    assert "update" in detail


def test_a_silent_sources_type_is_dead():
    state, _ = verdict("source.chargeable", FIRED)
    assert state == "dead"


def test_a_sources_type_that_still_fires_is_not_dead():
    # Still firing means something still creates Sources. That is a migration
    # finding, not a subscription to delete.
    state, _ = verdict("customer.source.expiring", FIRED)
    assert state == "legacy"


def test_silence_on_a_current_type_is_not_decay():
    # Zero disputes in 30 days is a good month. Calling this dead would have the
    # script recommend unsubscribing from disputes.
    state, detail = verdict("charge.dispute.created", FIRED)
    assert state == "quiet"
    assert "low volume" in detail


def test_a_wildcard_has_nothing_to_diff():
    assert verdict("*", FIRED)[0] == "wildcard"

import { test } from 'node:test';
import assert from 'node:assert/strict';
import { verdict } from './stripe-dead-event-types.mjs';

const FIRED = ['payment_intent.succeeded', 'invoice.paid',
               'customer.source.expiring'];

test('a removed type is rejected', () => {
  const [state, detail] = verdict('invoiceitem.updated', FIRED);
  assert.equal(state, 'rejected');
  assert.match(detail, /update/);
});

test('a silent sources type is dead', () => {
  assert.equal(verdict('source.chargeable', FIRED)[0], 'dead');
});

test('a sources type that still fires is not dead', () => {
  assert.equal(verdict('customer.source.expiring', FIRED)[0], 'legacy');
});

test('silence on a current type is not decay', () => {
  const [state, detail] = verdict('charge.dispute.created', FIRED);
  assert.equal(state, 'quiet');
  assert.match(detail, /low volume/);
});

test('a wildcard has nothing to diff', () => {
  assert.equal(verdict('*', FIRED)[0], 'wildcard');
});