a webhook endpoint sits disabled after days of retries

"""Report Stripe webhook endpoints that are disabled or losing events.

Read only. Two GET requests, 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_webhook_health")

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


def verdict(endpoint, undelivered):
    """Classify one endpoint. Pure, so the rules can be tested without a network.

    Returns (state, detail). `undelivered` is the count of failed deliveries seen
    for this endpoint in the retained window.
    """
    status = endpoint.get("status")
    if status == "disabled":
        return ("disabled",
                "Stripe stopped delivering after repeated failures. "
                "Re-enable only after the handler answers 2xx.")
    if status != "enabled":
        return ("unknown", "unrecognised status %r" % (status,))
    if undelivered:
        return ("failing",
                "%d event(s) did not deliver. The endpoint is still enabled, so "
                "you have time before Stripe disables it." % undelivered)
    return ("healthy", "delivering normally")


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 undelivered_by_endpoint(session, limit):
    """Count failed deliveries per endpoint id.

    Stripe returns the destinations an event failed to reach, so the count is
    attributed rather than guessed. Events are retained for 30 days; anything
    older than that cannot be replayed and is not counted here.
    """
    counts = {}
    total = 0
    params = {"delivery_success": "false", "limit": 100}
    while True:
        page = get(session, "/events", **params)
        for ev in page.get("data", []):
            total += 1
            for dest in ev.get("pending_webhooks_destinations", []) or []:
                counts[dest] = counts.get(dest, 0) + 1
        if not page.get("has_more") or total >= limit:
            break
        params["starting_after"] = page["data"][-1]["id"]
    return counts, total


def main():
    ap = argparse.ArgumentParser(description=__doc__)
    ap.add_argument("--max-events", type=int, default=1000,
                    help="stop counting undelivered events after this many")
    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

    per_endpoint, total_undelivered = undelivered_by_endpoint(s, args.max_events)

    bad = 0
    for ep in endpoints:
        state, detail = verdict(ep, per_endpoint.get(ep["id"], 0))
        line = "%-9s %s  %s" % (state, ep.get("url", "?"), detail)
        if state == "healthy":
            log.info(line)
            continue
        bad += 1
        log.warning(line)
        if state == "disabled":
            log.warning("  repair: POST %s/webhook_endpoints/%s -d disabled=false",
                        API, ep["id"])
            log.warning("  then replay: GET %s/events?delivery_success=false", API)

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


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

/**
 * Report Stripe webhook endpoints that are disabled or losing events.
 *
 * Read only. Two GET requests, 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 endpoint. Pure, so the rules can be tested without a network.
 */
export function verdict(endpoint, undelivered) {
  const status = endpoint.status;
  if (status === 'disabled') {
    return ['disabled',
      'Stripe stopped delivering after repeated failures. Re-enable only after ' +
      'the handler answers 2xx.'];
  }
  if (status !== 'enabled') {
    return ['unknown', `unrecognised status ${JSON.stringify(status)}`];
  }
  if (undelivered) {
    return ['failing',
      `${undelivered} event(s) did not deliver. The endpoint is still enabled, ` +
      'so you have time before Stripe disables it.'];
  }
  return ['healthy', 'delivering normally'];
}

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 undeliveredByEndpoint(key, limit = 1000) {
  const counts = new Map();
  let total = 0;
  const params = { delivery_success: 'false', limit: 100 };
  for (;;) {
    const page = await get(key, '/events', params);
    for (const ev of page.data ?? []) {
      total += 1;
      for (const dest of ev.pending_webhooks_destinations ?? []) {
        counts.set(dest, (counts.get(dest) ?? 0) + 1);
      }
    }
    if (!page.has_more || total >= limit) break;
    params.starting_after = page.data[page.data.length - 1].id;
  }
  return { counts, 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: 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, total } = await undeliveredByEndpoint(key);

  let bad = 0;
  for (const ep of endpoints) {
    const [state, detail] = verdict(ep, counts.get(ep.id) ?? 0);
    const line = `${state.padEnd(9)} ${ep.url ?? '?'}  ${detail}`;
    if (state === 'healthy') { console.log(line); continue; }
    bad += 1;
    console.warn(line);
    if (state === 'disabled') {
      console.warn(`  repair: POST ${API}/webhook_endpoints/${ep.id} -d disabled=false`);
      console.warn(`  then replay: GET ${API}/events?delivery_success=false`);
    }
  }

  console.log(`${endpoints.length} endpoint(s), ${bad} needing attention, ` +
              `${total} undelivered event(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_webhook_health import verdict


def test_disabled_endpoint_is_reported_regardless_of_event_count():
    state, detail = verdict({"status": "disabled"}, 0)
    assert state == "disabled"
    assert "2xx" in detail


def test_enabled_and_quiet_is_healthy():
    state, _ = verdict({"status": "enabled"}, 0)
    assert state == "healthy"


def test_enabled_with_failures_is_its_own_state():
    # The point of the note: this is the window before Stripe disables it.
    state, detail = verdict({"status": "enabled"}, 12)
    assert state == "failing"
    assert "12" in detail


def test_unknown_status_is_not_silently_healthy():
    state, _ = verdict({"status": "paused"}, 0)
    assert state == "unknown"


def test_missing_status_is_not_silently_healthy():
    state, _ = verdict({}, 0)
    assert state == "unknown"

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

test('disabled endpoint is reported regardless of event count', () => {
  const [state, detail] = verdict({ status: 'disabled' }, 0);
  assert.equal(state, 'disabled');
  assert.match(detail, /2xx/);
});

test('enabled and quiet is healthy', () => {
  assert.equal(verdict({ status: 'enabled' }, 0)[0], 'healthy');
});

test('enabled with failures is its own state', () => {
  const [state, detail] = verdict({ status: 'enabled' }, 12);
  assert.equal(state, 'failing');
  assert.match(detail, /12/);
});

test('unknown status is not silently healthy', () => {
  assert.equal(verdict({ status: 'paused' }, 0)[0], 'unknown');
});

test('missing status is not silently healthy', () => {
  assert.equal(verdict({}, 0)[0], 'unknown');
});