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.

[clerk-cookie]

Hello 👋

We currently close PRs after 60 days of inactivity. It's been 50 days since the last update here. If we missed this PR, please reply here. Otherwise, we'll close this PR in 10 days.

Thanks for being a part of the Clerk community! 🙏