feat(backend,react-router,nuxt,astro,nextjs,tanstack-react-start,express,fastify): Add verify webhook function

[wobsoriano]

Description

Right now, customers have to implement webhook verification when receiving Clerk webhooks to sync data with their apps using this guide. This PR abstracts away the majority of that logic, and makes it built-in across our backend and full-stack SDKs.

The verification can now be done with a single function call:

import { verifyWebhook } from '@clerk/backend/webhooks';
// Or from your framework-specific package:
// import { verifyWebhook } from '@clerk/nextjs/webhooks';

try {
  const evt = await verifyWebhook(request);
  if (evt.type === 'user.created') {
    // Handle user creation
    console.log('New user created:', evt.data.id);
  }
} catch (err) {
  // Invalid webhook signature
  return new Response('Webhook verification failed', { status: 400 });
}

Most of our SDKs provide a web standard Request object that can be passed directly to the verifyWebhook function. For Express and Fastify, we've added framework-specific support so that users can pass their route request object directly.

We also marked svix as an optional peer dependency for users not using webhooks.

Did some local tests to the ff. SDKs:

• ✅ Express
• ✅ Fastify
• ✅ Nuxt
• ✅ Nextjs

Resolves ECO-533

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: 2a73cdc

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-react-start	Minor
@clerk/fastify	Minor
@clerk/react-router	Minor
@clerk/backend	Minor
@clerk/express	Minor
@clerk/nextjs	Minor
@clerk/astro	Minor
@clerk/nuxt	Minor
@clerk/agent-toolkit	Patch
@clerk/remix	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	Apr 3, 2025 3:51am

[LekoArts]

Unless intended, a nice DX touch would be to inform the user which header is missing

[wobsoriano]

Updated to have more info about missing headers!

[brkalow]

👏 left one minor comment, otherwise LGTM

[brkalow]

Can we use the actual env var name here?

[wobsoriano]

💯 updated!

[LekoArts]

Nice 👏

[mlafeldt]

@wobsoriano Hey, I just wanted to bring svix/svix-webhooks#1483 to your attention. Using svix instead of standardwebhooks (also by the Svix guys) will significantly impact bundle size. Switching packages is actually pretty straightforward. See my comments in the linked issue.

[wobsoriano]

@wobsoriano Hey, I just wanted to bring svix/svix-webhooks#1483 to your attention. Using svix instead of standardwebhooks (also by the Svix guys) will significantly impact bundle size. Switching packages is actually pretty straightforward. See my comments in the linked issue.

This is noted 🫡