two endpoints share one URL, so every event is handled twice

"""Report Stripe webhook endpoints that share a URL and deliver every event twice.

Read only. GETs only, 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
from urllib.parse import urlsplit

import requests

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

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


def normalise(url):
    """Reduce a webhook URL to the destination it actually is. Pure.

    Stripe's own API-version upgrade procedure tells you to create the second
    endpoint with a query parameter, so the query string is exactly what makes a
    duplicate look distinct. Strip it, strip a trailing slash, lowercase the host.
    """
    parts = urlsplit((url or "").strip())
    host = (parts.hostname or "").lower()
    if parts.port:
        host = "%s:%d" % (host, parts.port)
    path = parts.path.rstrip("/")
    return "%s://%s%s" % ((parts.scheme or "").lower(), host, path)


def verdict(group):
    """Classify one group of endpoints sharing a normalised URL and mode. Pure.

    Returns (state, detail).
    """
    if not group:
        return ("unique", "no endpoints")
    enabled = [e for e in group if e.get("status") == "enabled"]
    if len(enabled) > 1:
        return ("duplicate",
                "%d enabled endpoints on one URL: every subscribed event is "
                "delivered %d times and both signatures verify."
                % (len(enabled), len(enabled)))
    if len(group) > 1:
        return ("residue",
                "%d endpoint(s) on this URL, %d enabled. The disabled ones are "
                "leftovers, not duplicates." % (len(group), len(enabled)))
    return ("unique", "%d enabled endpoint" % len(enabled))


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 group_endpoints(endpoints):
    """Group by (livemode, normalised url). Pure, given the endpoint list."""
    groups = {}
    for ep in endpoints:
        key = (bool(ep.get("livemode")), normalise(ep.get("url")))
        groups.setdefault(key, []).append(ep)
    return groups


def main():
    ap = argparse.ArgumentParser(description=__doc__)
    ap.add_argument("--corroborate", action="store_true",
                    help="also read recent events and report pending_webhooks")
    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

    bad = 0
    for (livemode, url), group in sorted(group_endpoints(endpoints).items()):
        state, detail = verdict(group)
        mode = "live" if livemode else "test"
        line = "%-10s %s %s  %s" % (state, mode, url, detail)
        if state == "unique":
            log.info(line)
            continue
        if state == "residue":
            log.info(line)
            continue
        bad += 1
        log.warning(line)
        for ep in group:
            log.warning("    %s  %s  version=%s  %d event type(s)",
                        ep["id"], ep.get("status"),
                        ep.get("api_version") or "account default",
                        len(ep.get("enabled_events") or []))
        keep = group[0]["id"]
        for ep in group[1:]:
            log.warning("  repair: keep %s, then "
                        "POST %s/webhook_endpoints/%s -d disabled=true",
                        keep, API, ep["id"])
        log.warning("  then make the handler idempotent on event.id, which is "
                    "required regardless: Stripe delivers at least once.")

    if args.corroborate:
        recent = get(s, "/events", limit=20).get("data", [])
        pending = [e.get("pending_webhooks", 0) for e in recent]
        if pending:
            log.info("recent events: pending_webhooks max=%d (1 per subscribed "
                     "destination while in flight)", max(pending))

    log.info("%d endpoint(s), %d duplicated URL group(s)", len(endpoints), bad)
    return 1 if bad else 0


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

/**
 * Report Stripe webhook endpoints that share a URL and deliver every event twice.
 *
 * Read only. GETs only, 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';

/**
 * Reduce a webhook URL to the destination it actually is. Pure.
 *
 * Stripe's own API-version upgrade procedure tells you to create the second
 * endpoint with a query parameter, so the query string is exactly what makes a
 * duplicate look distinct. Strip it, strip a trailing slash, lowercase the host.
 */
export function normalise(url) {
  let parsed;
  try {
    parsed = new URL(String(url ?? '').trim());
  } catch {
    return String(url ?? '').trim();
  }
  const path = parsed.pathname.replace(/\/+$/, '');
  return `${parsed.protocol.replace(':', '').toLowerCase()}://${parsed.host.toLowerCase()}${path}`;
}

/**
 * Classify one group of endpoints sharing a normalised URL and mode. Pure.
 */
export function verdict(group) {
  const items = group ?? [];
  if (items.length === 0) return ['unique', 'no endpoints'];
  const enabled = items.filter((e) => e.status === 'enabled');
  if (enabled.length > 1) {
    return ['duplicate',
      `${enabled.length} enabled endpoints on one URL: every subscribed event is ` +
      `delivered ${enabled.length} times and both signatures verify.`];
  }
  if (items.length > 1) {
    return ['residue',
      `${items.length} endpoint(s) on this URL, ${enabled.length} enabled. ` +
      'The disabled ones are leftovers, not duplicates.'];
  }
  return ['unique', `${enabled.length} enabled endpoint`];
}

export function groupEndpoints(endpoints) {
  const groups = new Map();
  for (const ep of endpoints) {
    const key = `${ep.livemode ? 'live' : 'test'} ${normalise(ep.url)}`;
    if (!groups.has(key)) groups.set(key, []);
    groups.get(key).push(ep);
  }
  return groups;
}

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();
}

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;
  }

  let bad = 0;
  for (const [label, group] of [...groupEndpoints(endpoints).entries()].sort()) {
    const [state, detail] = verdict(group);
    const line = `${state.padEnd(10)} ${label}  ${detail}`;
    if (state !== 'duplicate') { console.log(line); continue; }
    bad += 1;
    console.warn(line);
    for (const ep of group) {
      console.warn(`    ${ep.id}  ${ep.status}  version=` +
                   `${ep.api_version ?? 'account default'}  ` +
                   `${(ep.enabled_events ?? []).length} event type(s)`);
    }
    const keep = group[0].id;
    for (const ep of group.slice(1)) {
      console.warn(`  repair: keep ${keep}, then ` +
                   `POST ${API}/webhook_endpoints/${ep.id} -d disabled=true`);
    }
    console.warn('  then make the handler idempotent on event.id, which is ' +
                 'required regardless: Stripe delivers at least once.');
  }

  console.log(`${endpoints.length} endpoint(s), ${bad} duplicated URL group(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_duplicate_endpoints import normalise, verdict


def test_query_string_does_not_make_a_new_destination():
    # Stripe's version-upgrade guide tells you to add exactly this parameter.
    a = normalise("https://example.com/stripe/webhook?v=2025-09-30")
    b = normalise("https://example.com/stripe/webhook")
    assert a == b


def test_trailing_slash_and_host_case_are_ignored():
    a = normalise("https://Example.COM/stripe/webhook/")
    b = normalise("https://example.com/stripe/webhook")
    assert a == b


def test_different_paths_stay_different():
    assert normalise("https://example.com/a") != normalise("https://example.com/b")


def test_two_enabled_endpoints_on_one_url_is_the_finding():
    state, detail = verdict([{"status": "enabled"}, {"status": "enabled"}])
    assert state == "duplicate"
    assert "2 times" in detail


def test_one_enabled_beside_a_disabled_one_is_only_residue():
    state, _ = verdict([{"status": "enabled"}, {"status": "disabled"}])
    assert state == "residue"


def test_a_single_endpoint_is_unique():
    assert verdict([{"status": "enabled"}])[0] == "unique"

import { test } from 'node:test';
import assert from 'node:assert/strict';
import { normalise, verdict } from './stripe-duplicate-endpoints.mjs';

test('query string does not make a new destination', () => {
  // Stripe's version-upgrade guide tells you to add exactly this parameter.
  assert.equal(
    normalise('https://example.com/stripe/webhook?v=2025-09-30'),
    normalise('https://example.com/stripe/webhook'));
});

test('trailing slash and host case are ignored', () => {
  assert.equal(
    normalise('https://Example.COM/stripe/webhook/'),
    normalise('https://example.com/stripe/webhook'));
});

test('different paths stay different', () => {
  assert.notEqual(normalise('https://example.com/a'),
                  normalise('https://example.com/b'));
});

test('two enabled endpoints on one url is the finding', () => {
  const [state, detail] = verdict([{ status: 'enabled' }, { status: 'enabled' }]);
  assert.equal(state, 'duplicate');
  assert.match(detail, /2 times/);
});

test('one enabled beside a disabled one is only residue', () => {
  assert.equal(verdict([{ status: 'enabled' }, { status: 'disabled' }])[0], 'residue');
});

test('a single endpoint is unique', () => {
  assert.equal(verdict([{ status: 'enabled' }])[0], 'unique');
});