fix(providers): retire the duplicate customerio slug and pin the published counts

[choraria]

The duplicate

The registry carried two slugs for one real provider. customerio and customer_io had
byte-identical schemes — same x-cio-signature / x-cio-timestamp headers, same hex encoding, same
v0:{ts}:{body} signed message, same tolerance — and both rendered as "Customer.io", so the /verify
provider picker and the docs directory each listed Customer.io twice.

customer_io survives: it matches the convention every other dotted-domain brand follows (cal_com,
checkout_com, incident_io, merge_dev). PROVIDERS is now 141.

Why this isn't just a vocabulary edit

provider_secrets.provider is plain text with no enum and no CHECK, and the engine picks an adapter
from the registered provider. A slug that stops resolving is dropped, not rejected — so an
endpoint registered under customerio would not error and would not warn. It would simply stop
verifying and start landing events unverified.

So the alias lives in canonicalProvider, the one place stored free text becomes a Provider, and the
code does not depend on the migration having run:

• webhooks-spec — RETIRED_PROVIDER_ALIASES + a shared canonicalProvider, replacing the
  engine's local copy. A retired slug resolves; the write path (ProviderSchema) still rejects it, so
  nothing new can register under one.
• packages/db reads — events and provider-secret rows canonicalise on the way out, so a legacy
  value can never reach EventSummarySchema / ProviderSecretSummarySchema (both strict) and break a
  whole list. The public API, the generated SDKs and the dashboard never see the dead slug.
• Migration 0095 — hygiene, not a rescue. Rewrites the stored rows so the data stops disagreeing
  with the vocabulary and the provider filter returns historical rows.

The migration is bounded, and that's verified

events is the largest table and its only provider index leads with endpoint_id, so a bare
where provider = 'customerio' would scan all of it. The affected endpoints are knowable up front, and
the set is exhaustive, not a heuristic: the engine names an event's provider from the endpoint's
registered secret; revoke is a soft delete and nothing hard-deletes provider_secrets; and both tables
cascade from endpoints/orgs, so there are no orphan events. A DO block skips the events statement
entirely when there are none, making "we did not touch events" a certainty rather than a planner choice.

Exercised against a real Postgres 14 (matching CI):

check	result
rewrites events + secrets, including a revoked secret's endpoint	✅
leaves unrelated endpoints untouched	✅
idempotent on re-run	✅
in the empty case, a statement-level tripwire proves the events UPDATE never executes	✅

Two counts that were already wrong

The docs split the registry "around 109 config-driven / the remaining 33 bespoke" — a plausible pair
that summed to the headline and matched the code in neither half. Twilio has both a config row and
a bespoke adapter, and registry.ts prefers the bespoke one, so its config row never runs. The real
partition is 108 / 33. Nobody noticed, because a number typed into prose has no relationship to the
registry it describes.

published-counts.test.ts now pins every published count to the live registry across docs, the
marketing site and the README, and asserts the provider directory lists exactly the live set — the
check that would have caught this duplicate at the source, which no count ever could (the number was
self-consistently wrong).

Mutation-verified

Every guard here was checked red before being trusted:

• drop the alias from canonicalProvider → the legacy secret verifies false, silently. That's
  the exact failure mode, reproduced.
• put a stale count back in one doc → fails, naming the file and fragment.
• empty a manifest entry → the zero-input floor fires.
• smuggle a live slug into RETIRED_PROVIDERS → fails.
• add a dead branding key → still caught.

The w1-batch3 known-answer test was retargeted rather than deleted — it was Customer.io's only
replay-window and header-metadata coverage (s8-crypto-finds covers verify + framing only).

Test plan

• pnpm lint ✅ (402 guard tests) · pnpm typecheck ✅ 32/32 · pnpm test ✅ 28/28
• Migration behaviour verified against a real Postgres 14 as tabled above.
• test-db (CI) covers up → down → up reversibility; migrate:down is deliberately a no-op — the two
  slugs are indistinguishable once normalised, so restoring the wrong ones would be worse than leaving
  them.

⚠️ For the founder

1. Migration 0095 needs applying — this session is prod-DB blocked, so I could not run it against
   production. The code is safe either way (the alias means nothing breaks if it hasn't run yet).
2. Removing an enum member from the published @webhook-co/sdk is semver-relevant. The generated
   Provider union loses "customerio". Nothing could legitimately have been using it — it verified
   identically to customer_io — but it is a type-level breaking change worth a release note.

🤖 Generated with Claude Code

https://claude.ai/code/session_01XiZ2XWyU6gUDa9rT8iYqvL

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
webhook-co	🟢 Ready	View Preview	Jul 21, 2026, 5:17 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
webhook-co	🟡 Building	–	Jul 21, 2026, 5:17 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.