feat(astro, backend, express, fastify, nextjs, nuxt, react-router, remix, tanstack-start): Introduce WebhookEventPayload<TWebhookEventType> for extracting typed webhook payloads

[MlNl-PEKKA]

Description

Introduces WebhookEventPayload<TWebhookEventType>, a utility type that allows to infer webhook payloads based on event types.

Usage:

type UserCreatedPayload = WebhookEventPayload<"user.created">;
//   ^? { 
//          object: "event";
//          data: UserJSON;
//          type: "user.created";
//      }

Motivation

Currently, there isn't a way to easily extract the WebhookEventPayload type based on the WebhookEventType.

type EmailCreatedPayload = Extract<WebhookEvent, { type: 'email.created' } >
//   ^? { 
//          object: "event";
//          data: EmailJSON;
//          type: "email.created";
//      }
// Works as expected

type UserCreatedPayload = Extract<WebhookEvent, { type: 'user.created' }>
//     ^? never
//  Fails, because "type" for { data: UserJSON } is a union, 'user.created' | 'user.updated'

type UserCreatedPayload = Extract<WebhookEvent, { type: 'user.created' | 'user.updated' }>
//     ^? { 
//          object: "event";
//          data: UserJSON;
//          type: 'user.created' | 'user.updated';
//      }
// Works as Expected

Checklist

• pnpm test runs as expected.
• pnpm build runs as expected.
• (If applicable) JSDoc comments have been added or updated for any package exports
• (If applicable) Documentation has been updated

Type of change

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other:

[changeset-bot]

🦋 Changeset detected

Latest commit: 555a575

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 11 packages

Name	Type
@clerk/tanstack-start	Minor
@clerk/react-router	Minor
@clerk/backend	Minor
@clerk/nextjs	Minor
@clerk/astro	Minor
@clerk/remix	Minor
@clerk/express	Minor
@clerk/fastify	Minor
@clerk/nuxt	Minor
@clerk/agent-toolkit	Patch
@clerk/testing	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
clerk-js-sandbox	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Feb 28, 2025 7:37pm

[MlNl-PEKKA]

I've carefully tracked all the packages where WebhookEvent and related types are being imported/exported. There were also barrel exports in certain packages, making this a bit hard to track. It'd be much appreciated if anybody could confirm the packages mentioned above.