feat(backend,react-router,nuxt,astro,nextjs,tanstack-react-start,express,fastify): Add verify webhook function by wobsoriano · Pull Request #5468 · clerk/javascript

wobsoriano · 2025-03-27T18:18:37Z

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{constevt=awaitverifyWebhook(request);if(evt.type==='user.created'){// Handle user creationconsole.log('New user created:',evt.data.id);}}catch(err){// Invalid webhook signaturereturnnewResponse('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

changeset-bot · 2025-03-27T18:18:41Z

🦋 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 · 2025-03-27T18:18:42Z

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

…function

LekoArts · 2025-04-02T07:49:58Z

+ }
+
+ if (!svixId || !svixTimestamp || !svixSignature) {
+ return errorThrower.throw('Missing required Svix headers.');


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

Updated to have more info about missing headers!

Co-authored-by: Lennart <lekoarts@gmail.com>

brkalow

👏 left one minor comment, otherwise LGTM

brkalow · 2025-04-03T03:27:01Z

+ const svixSignature = request.headers.get(SVIX_SIGNATURE_HEADER);
+
+ if (!secret) {
+ return errorThrower.throw('Missing signing secret. Please add it to your environment variables.');


Can we use the actual env var name here?

💯 updated!

…rror

LekoArts · 2025-04-03T07:38:33Z

Nice 👏

mlafeldt · 2025-04-09T15:55:40Z

@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 · 2025-04-09T16:35:14Z

@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 🫡

wobsoriano · 2025-03-27T18:18:37Z

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{constevt=awaitverifyWebhook(request);if(evt.type==='user.created'){// Handle user creationconsole.log('New user created:',evt.data.id);}}catch(err){// Invalid webhook signaturereturnnewResponse('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

changeset-bot · 2025-03-27T18:18:41Z

🦋 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 · 2025-03-27T18:18:42Z

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

…function

LekoArts · 2025-04-02T07:49:58Z

+ }
+
+ if (!svixId || !svixTimestamp || !svixSignature) {
+ return errorThrower.throw('Missing required Svix headers.');


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

Updated to have more info about missing headers!

Co-authored-by: Lennart <lekoarts@gmail.com>

brkalow

👏 left one minor comment, otherwise LGTM

brkalow · 2025-04-03T03:27:01Z

+ const svixSignature = request.headers.get(SVIX_SIGNATURE_HEADER);
+
+ if (!secret) {
+ return errorThrower.throw('Missing signing secret. Please add it to your environment variables.');


Can we use the actual env var name here?

💯 updated!

…rror

LekoArts · 2025-04-03T07:38:33Z

Nice 👏

mlafeldt · 2025-04-09T15:55:40Z

@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 · 2025-04-09T16:35:14Z

@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 🫡

wobsoriano · 2025-03-27T18:18:37Z

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{constevt=awaitverifyWebhook(request);if(evt.type==='user.created'){// Handle user creationconsole.log('New user created:',evt.data.id);}}catch(err){// Invalid webhook signaturereturnnewResponse('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

changeset-bot · 2025-03-27T18:18:41Z

🦋 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 · 2025-03-27T18:18:42Z

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

…function

LekoArts · 2025-04-02T07:49:58Z

+ }
+
+ if (!svixId || !svixTimestamp || !svixSignature) {
+ return errorThrower.throw('Missing required Svix headers.');


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

Updated to have more info about missing headers!

Co-authored-by: Lennart <lekoarts@gmail.com>

brkalow

👏 left one minor comment, otherwise LGTM

brkalow · 2025-04-03T03:27:01Z

+ const svixSignature = request.headers.get(SVIX_SIGNATURE_HEADER);
+
+ if (!secret) {
+ return errorThrower.throw('Missing signing secret. Please add it to your environment variables.');


Can we use the actual env var name here?

💯 updated!

…rror

LekoArts · 2025-04-03T07:38:33Z

Nice 👏

mlafeldt · 2025-04-09T15:55:40Z

@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 · 2025-04-09T16:35:14Z

@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 🫡

wobsoriano · 2025-03-27T18:18:37Z

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{constevt=awaitverifyWebhook(request);if(evt.type==='user.created'){// Handle user creationconsole.log('New user created:',evt.data.id);}}catch(err){// Invalid webhook signaturereturnnewResponse('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

changeset-bot · 2025-03-27T18:18:41Z

🦋 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 · 2025-03-27T18:18:42Z

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

…function

LekoArts · 2025-04-02T07:49:58Z

+ }
+
+ if (!svixId || !svixTimestamp || !svixSignature) {
+ return errorThrower.throw('Missing required Svix headers.');


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

Updated to have more info about missing headers!

Co-authored-by: Lennart <lekoarts@gmail.com>

brkalow

👏 left one minor comment, otherwise LGTM

brkalow · 2025-04-03T03:27:01Z

+ const svixSignature = request.headers.get(SVIX_SIGNATURE_HEADER);
+
+ if (!secret) {
+ return errorThrower.throw('Missing signing secret. Please add it to your environment variables.');


Can we use the actual env var name here?

💯 updated!

…rror

LekoArts · 2025-04-03T07:38:33Z

Nice 👏

mlafeldt · 2025-04-09T15:55:40Z

@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 · 2025-04-09T16:35:14Z

@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 🫡

wobsoriano · 2025-03-27T18:18:37Z

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{constevt=awaitverifyWebhook(request);if(evt.type==='user.created'){// Handle user creationconsole.log('New user created:',evt.data.id);}}catch(err){// Invalid webhook signaturereturnnewResponse('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

changeset-bot · 2025-03-27T18:18:41Z

🦋 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 · 2025-03-27T18:18:42Z

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

…function

LekoArts · 2025-04-02T07:49:58Z

+ }
+
+ if (!svixId || !svixTimestamp || !svixSignature) {
+ return errorThrower.throw('Missing required Svix headers.');


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

Updated to have more info about missing headers!

Co-authored-by: Lennart <lekoarts@gmail.com>

brkalow

👏 left one minor comment, otherwise LGTM

brkalow · 2025-04-03T03:27:01Z

+ const svixSignature = request.headers.get(SVIX_SIGNATURE_HEADER);
+
+ if (!secret) {
+ return errorThrower.throw('Missing signing secret. Please add it to your environment variables.');


Can we use the actual env var name here?

💯 updated!

…rror

LekoArts · 2025-04-03T07:38:33Z

Nice 👏

mlafeldt · 2025-04-09T15:55:40Z

@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 · 2025-04-09T16:35:14Z

@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 🫡

wobsoriano · 2025-03-27T18:18:37Z

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{constevt=awaitverifyWebhook(request);if(evt.type==='user.created'){// Handle user creationconsole.log('New user created:',evt.data.id);}}catch(err){// Invalid webhook signaturereturnnewResponse('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

changeset-bot · 2025-03-27T18:18:41Z

🦋 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 · 2025-03-27T18:18:42Z

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

…function

LekoArts · 2025-04-02T07:49:58Z

+ }
+
+ if (!svixId || !svixTimestamp || !svixSignature) {
+ return errorThrower.throw('Missing required Svix headers.');


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

Updated to have more info about missing headers!

Co-authored-by: Lennart <lekoarts@gmail.com>

brkalow

👏 left one minor comment, otherwise LGTM

brkalow · 2025-04-03T03:27:01Z

+ const svixSignature = request.headers.get(SVIX_SIGNATURE_HEADER);
+
+ if (!secret) {
+ return errorThrower.throw('Missing signing secret. Please add it to your environment variables.');


Can we use the actual env var name here?

💯 updated!

…rror

LekoArts · 2025-04-03T07:38:33Z

Nice 👏

mlafeldt · 2025-04-09T15:55:40Z

@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 · 2025-04-09T16:35:14Z

@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 🫡

wobsoriano · 2025-03-27T18:18:37Z

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{constevt=awaitverifyWebhook(request);if(evt.type==='user.created'){// Handle user creationconsole.log('New user created:',evt.data.id);}}catch(err){// Invalid webhook signaturereturnnewResponse('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

changeset-bot · 2025-03-27T18:18:41Z

🦋 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 · 2025-03-27T18:18:42Z

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

…function

LekoArts · 2025-04-02T07:49:58Z

+ }
+
+ if (!svixId || !svixTimestamp || !svixSignature) {
+ return errorThrower.throw('Missing required Svix headers.');


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

Updated to have more info about missing headers!

Co-authored-by: Lennart <lekoarts@gmail.com>

brkalow

👏 left one minor comment, otherwise LGTM

brkalow · 2025-04-03T03:27:01Z

+ const svixSignature = request.headers.get(SVIX_SIGNATURE_HEADER);
+
+ if (!secret) {
+ return errorThrower.throw('Missing signing secret. Please add it to your environment variables.');


Can we use the actual env var name here?

💯 updated!

…rror

LekoArts · 2025-04-03T07:38:33Z

Nice 👏

mlafeldt · 2025-04-09T15:55:40Z

@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 · 2025-04-09T16:35:14Z

@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 🫡

wobsoriano · 2025-03-27T18:18:37Z

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{constevt=awaitverifyWebhook(request);if(evt.type==='user.created'){// Handle user creationconsole.log('New user created:',evt.data.id);}}catch(err){// Invalid webhook signaturereturnnewResponse('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

changeset-bot · 2025-03-27T18:18:41Z

🦋 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 · 2025-03-27T18:18:42Z

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

…function

LekoArts · 2025-04-02T07:49:58Z

+ }
+
+ if (!svixId || !svixTimestamp || !svixSignature) {
+ return errorThrower.throw('Missing required Svix headers.');


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

Updated to have more info about missing headers!

Co-authored-by: Lennart <lekoarts@gmail.com>

brkalow

👏 left one minor comment, otherwise LGTM

brkalow · 2025-04-03T03:27:01Z

+ const svixSignature = request.headers.get(SVIX_SIGNATURE_HEADER);
+
+ if (!secret) {
+ return errorThrower.throw('Missing signing secret. Please add it to your environment variables.');


Can we use the actual env var name here?

💯 updated!

…rror

LekoArts · 2025-04-03T07:38:33Z

Nice 👏

mlafeldt · 2025-04-09T15:55:40Z

@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 · 2025-04-09T16:35:14Z

@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 🫡

feat(backend): Add verify webhook function
7ef79e7

clerk-cookie added the backend label Mar 27, 2025

vercelBotdeployed to Preview March 27, 2025 18:19 View deployment

feat(nextjs,react-router,nuxt,astro): Re-export webhook verification …
d92897e
…function

vercelBottemporarily deployed to Preview March 27, 2025 18:32 Inactive

wobsoriano changed the title ~~feat(backend): Add verify webhook function~~feat(backend,react-router,nuxt,astro,nextjs): Add verify webhook functionMar 27, 2025

clerk-cookie added nextjs astro react-router nuxt labels Mar 27, 2025

feat(tanstack-react-start): Add webhook util
2e13561

vercelBottemporarily deployed to Preview March 27, 2025 19:18 Inactive

clerk-cookie added the tanstack label Mar 27, 2025

wobsoriano changed the title ~~feat(backend,react-router,nuxt,astro,nextjs): Add verify webhook function~~feat(backend,react-router,nuxt,astro,nextjs,tanstack-react-start): Add verify webhook functionMar 27, 2025

chore: clean up and catch missing headers
6f158fa

wobsoriano changed the title ~~feat(backend,react-router,nuxt,astro,nextjs,tanstack-react-start): Add verify webhook function~~feat(backend,react-router,nuxt,astro,nextjs,tanstack-react-start,express,fastify): Add verify webhook functionMar 27, 2025

clerk-cookie added fastify express labels Mar 27, 2025

vercelBotdeployed to Preview March 27, 2025 21:43 View deployment

chore: correct env var name
92d58cf

vercelBotdeployed to Preview March 27, 2025 21:45 View deployment

chore: type clean up
5c87188

vercelBotdeployed to Preview March 27, 2025 22:11 View deployment

clerk deleted a comment from clerk-cookie Mar 27, 2025

Merge branch 'main' into rob/eco-533-internal-verify-webhook
74a9ee8

vercelBotdeployed to Preview March 27, 2025 22:17 View deployment

test: add error tests
5e11b1b

clerk deleted a comment from clerk-cookie Mar 27, 2025

vercelBottemporarily deployed to Preview April 2, 2025 04:17 Inactive

LekoArts reviewed Apr 2, 2025
View reviewed changes

wobsorianoand others added 4 commits April 2, 2025 08:57

Update .changeset/olive-apples-return.md
747c2c2
Co-authored-by: Lennart <lekoarts@gmail.com>

Update .changeset/olive-apples-return.md
74cf541
Co-authored-by: Lennart <lekoarts@gmail.com>

Update .changeset/olive-apples-return.md
c6efea0
Co-authored-by: Lennart <lekoarts@gmail.com>

Update .changeset/olive-apples-return.md
cc0e823
Co-authored-by: Lennart <lekoarts@gmail.com>

vercelBotdeployed to Preview April 2, 2025 16:00 View deployment

Merge branch 'main' into rob/eco-533-internal-verify-webhook
681ce0f

vercelBotdeployed to Preview April 3, 2025 00:58 View deployment

wobsoriano added 2 commits April 2, 2025 18:07

chore: Inform missing svix headers
fa44ae1

chore: separate changesets with examples
8df9097

vercelBotdeployed to Preview April 3, 2025 02:09 View deployment

brkalow approved these changes Apr 3, 2025
View reviewed changes

chore: Use actual env var name when throwing missing signing secret e…
2a73cdc
…rror

vercelBotdeployed to Preview April 3, 2025 03:51 View deployment

wobsoriano merged commit cd6ee92 into mainApr 3, 2025

wobsoriano deleted the rob/eco-533-internal-verify-webhook branch April 3, 2025 04:02

clerk-cookie mentioned this pull request Apr 3, 2025
ci(repo): Version packages #5466
Merged

wobsoriano mentioned this pull request Apr 3, 2025
Add docs using verifyWebhook per-SDK clerk/clerk-docs#2159
Merged
2 tasks

mwickett mentioned this pull request Apr 3, 2025
use new verifyWebhook clerk method mwickett/blitzer#141
Closed

wobsoriano mentioned this pull request Apr 14, 2025
chore(nextjs): Add support for pages router when verifying webhooks #5618
Merged
9 tasks

This was referenced Jun 21, 2026
feat: implement end-to-end encryption support for event photos and integrate decryption workflow into the slideshow component Asrar-Ahammad/momnts#14
Merged
[SWY-71] Add Clerk webhook user sync justaddcl/sanbi#94
Open

coderabbitaiBot mentioned this pull request Jul 18, 2026
Add Clerk authentication with webhook user sync Yedidyar/rituvo#5
Merged

coderabbitaiBot mentioned this pull request Jul 30, 2026
fix: add Clerk webhook handler and wire checkUser into middleware harshdwivediiiii/pathfinder-ai#1689
Merged

This was referenced Aug 17, 2026
feat: recipient booking Himanshu-Sorathiya-Simform/calendly#3
Open
basic backend added with routes Ayush-verma25/LMS-Website-App-MERN#3
Merged