feat(extras): receive SaaS webhooks, at flyte.extras.webhooks

[cosmicBboy]

First of a stack that replaces the six per-product integration plugins (#1502–#1507) with the parts that are genuinely Flyte's. Structured like plugins/agents: core holds the contract, each product is its own thin package.

Stack: this → github → slack → linear → clickup → jira → examples. Each PR's diff is just its own package.

What core owns

WebhookAppEnvironment	One app: a dashboard and a verified receiver at /webhook/{provider}, for whichever providers it is handed
Provider	The contract a product plugin implements
WebhookEvent	The normalized event every provider parses into
run_once	Launch a run once per event key, returning the run that covers it either way
EventType	Base for the typed event constants each plugin ships
verification primitives	constant_time_equals, hex_hmac_sha256, json_body, lower_headers
testing.assert_provider_conforms	The conformance check every plugin runs

A product plugin owns only what is specific to it — usually under 150 lines. Core is tested against a stub provider, so it depends on no product package.

Two decisions worth reviewing

Identity lives on a run label, never a name. run_once launches only when no run carrying the same dedupe label is live or succeeded; when one is, it returns that run with created=False rather than launching a second or raising, so a handler can answer "already handled" and link to it. Names race against concurrent launches and cap how many runs one key can ever have, so the control plane assigns them. It is async-first behind @syncify — the blocking form stalls an app's event loop, and webhook senders time out in seconds. A test asserts four concurrent launches overlap; against a blocking implementation it measures 0.81s instead of 0.42s and fails.

constant_time_equals compares bytes. hmac.compare_digest raises TypeError on str operands containing non-ASCII, and these headers come off the wire — ASGI hands Starlette raw bytes which it decodes latin-1, so a crafted header would turn a clean 401 into a 500. Writing it once here is the main argument for a shared core.

The conformance harness

Each product plugin ships SAMPLE_DELIVERY, a real payload. The harness signs and replays it, so verify and parse are checked against an actual payload rather than against each other — without one, every other check is vacuous.

It earned its keep during development twice:

• It caught that Jira's shared token is not bound to the request body, unlike the four HMAC providers. That is inherent to an unsigned webhook, not a bug, so signed=False now opts out of the body-tampering check and makes the dashboard say the product does not sign.
• It caught a hole in itself: the hostile-header check sent a bare non-ASCII value, which GitHub and Slack reject on their scheme prefix before reaching the comparison — leaving the check vacuous for exactly the two providers it mattered most for. Hostile values now preserve the prefix, and a str-based compare_digest fails conformance as intended.

I verified it discriminates by injecting three regressions (plain str, Enum constants, a str comparison, a constant that no longer matches the parser); each one fails with a specific message.

Notes

No new dependencies land in flyte: the shared core lives in flyte.extras.webhooks behind the same soft-import pattern the other flyte.extras apps use, and each product plugin ships its own provider.

46 core tests plus each plugin's suite. make fmt, make mypy (864 files), make ty, ruff, and codespell pass.

The caveat from the review that prompted this: the parsers still encode payload-shape assumptions I cannot verify without live accounts. That surface is much smaller now — the six API clients and their ~213 field assumptions are gone — and SAMPLE_DELIVERY pins what remains, but one real pass per product is still the thing that would confirm it.