webhook-inbound: default to v2, gate v1 via feature-flag+allowlist, add adoption metric & sunset warning

[adm01-debug]

Motivation

• Make v2 the default to enforce a structured envelope and reduce garbage persisted in inbound_webhook_events while preserving short-term compatibility for legacy senders.
• Restrict v1 usage to explicitly allowlisted legacy issuers behind a feature flag to accelerate migration and limit blast radius.
• Track adoption and communicate deprecation by adding runtime metrics and an earlier sunset date for v1.

Description

• Changed the contract defaultVersion from "1" to "2" and moved v1 sunset to 2026-06-30 in supabase/functions/_shared/contracts/schemas/webhook-inbound.ts.
• Added readRequestedVersion and parseAllowlist helpers and gating logic in supabase/functions/webhook-inbound/index.ts that enforces WEBHOOK_INBOUND_V1_COMPAT_ENABLED and WEBHOOK_INBOUND_V1_ALLOWLIST, returning 426 with code legacy_version_blocked when v1 is not allowed.
• Emit a structured adoption log webhook_inbound_contract_version_adoption (endpoint, issuer, contract_version, is_default_version, requested_version) and attach explicit deprecation Warning headers and a warning field in v1 successful responses.
• Added contract tests in supabase/functions/_shared/contracts/schemas/webhook-inbound.test.ts that assert the default (v2) rejects non-envelope payloads and that explicit v=1 still parses passthrough payloads.

Testing

• Attempted to run deno test supabase/functions/_shared/contracts/schemas/webhook-inbound.test.ts but it failed in this environment because the deno binary is not available (deno: command not found).
• No other automated tests were executed in this environment.

---

Codex Task

---

Summary by cubic

Switches the inbound webhook contract default to v2 and gates legacy v1 behind a feature flag and allowlist. Adds adoption metrics and deprecation warnings to speed migration and reduce junk payloads.

• New Features
  • Default webhook-inbound contract to v2 (strict envelope); v1 sunset set to 2026-06-30. Tests assert default rejects non-envelope and explicit v=1 still parses.
  • Gate v1 via WEBHOOK_INBOUND_V1_COMPAT_ENABLED + WEBHOOK_INBOUND_V1_ALLOWLIST; blocked requests return 426 with legacy_version_blocked.
  • Emit webhook_inbound_contract_version_adoption logs with endpoint, issuer, contract_version, is_default_version, and requested_version.
  • Add deprecation Warning headers and a warning field on successful v1 responses.

^{Written for commit 0d6186c. Summary will update on new commits. Review in cubic}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
we-dream-big	Ready	Preview, Comment	May 24, 2026 1:18am

[supabase]

This pull request has been ignored for the connected project doufsxqlfjyuvxuezpln due to reaching the limit of concurrent preview branches.
Go to Project Integrations Settings ↗︎ if you wish to update this limit.

---

Preview Branches by Supabase.
Learn more about Supabase Branching ↗︎.

[coderabbitai]

Warning

Review limit reached

@adm01-debug, we couldn't start this review because you've used your available PR reviews for now.

Your plan currently allows 1 review/hour. Refill in 37 minutes and 21 seconds.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more review capacity refills, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than trial, open-source, and free plans. In all cases, review capacity refills continuously over time.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: c78f330c-8312-42cf-a9d3-f14e8337a032

📥 Commits

Reviewing files that changed from the base of the PR and between 08f7f58 and 0d6186c.

📒 Files selected for processing (3)

• supabase/functions/_shared/contracts/schemas/webhook-inbound.test.ts
• supabase/functions/_shared/contracts/schemas/webhook-inbound.ts
• supabase/functions/webhook-inbound/index.ts

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/update-webhook-inbound-schema-and-add-metrics

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}