chore(nextjs): Add support for pages router when verifying webhooks

.changeset/free-actors-prove.md

@@ -0,0 +1,43 @@
+---
+'@clerk/nextjs': patch
+---
+
+Add support for webhook verification with Next.js Pages Router.
+
+```ts
+// Next.js Pages Router
+import type { NextApiRequest, NextApiResponse } from 'next'
+import { verifyWebhook } from '@clerk/nextjs/webhooks';
+
+export const config = {
+ api: {
+ bodyParser: false,
+ },
+}
+
+export default async function handler(
+ req: NextApiRequest,
+ res: NextApiResponse
+) {
+ try {
+ const evt = await verifyWebhook(req);
+ // Handle webhook event
+ res.status(200).json({ received: true });
+ } catch (err) {
+ res.status(400).json({ error: 'Webhook verification failed' });
+ }
+}
+
+// tRPC
+import { verifyWebhook } from '@clerk/nextjs/webhooks';
+
+const webhookRouter = router({
+ webhook: publicProcedure
+ .input(/** schema */)
+ .mutation(async ({ ctx }) => {
+ const evt = await verifyWebhook(ctx.req);
+ // Handle webhook event
+ return { received: true };
+ }),
+});
+```

packages/nextjs/src/__tests__/webhooks.test.ts

@@ -0,0 +1,94 @@
+import type { NextApiRequest } from 'next';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type { RequestLike } from '../server/types';
+import { verifyWebhook } from '../webhooks';
+
+const mockSuccessResponse = {
+ type: 'user.created',
+ data: { id: 'user_123' },
+ object: 'event',
+} as any;
+
+const mockError = new Error('Missing required Svix headers: svix-id, svix-timestamp, svix-signature');
+
+vi.mock('@clerk/backend/webhooks', () => ({
+ verifyWebhook: vi.fn().mockImplementation((request: Request) => {
+ const svixId = request.headers.get('svix-id');
+ const svixTimestamp = request.headers.get('svix-timestamp');
+ const svixSignature = request.headers.get('svix-signature');
+
+ if (!svixId || !svixTimestamp || !svixSignature) {
+ throw mockError;
+ }
+
+ return mockSuccessResponse;
+ }),
+}));
+
+describe('verifyWebhook', () => {
+ const mockSecret = 'test_signing_secret';
+ const mockBody = JSON.stringify(mockSuccessResponse);
+ const mockHeaders = {
+ 'svix-id': 'msg_123',
+ 'svix-timestamp': '1614265330',
+ 'svix-signature': 'v1,test_signature',
+ };
+
+ beforeEach(() => {
+ process.env.CLERK_WEBHOOK_SIGNING_SECRET = mockSecret;
+ });
+
+ describe('with standard Request', () => {
+ it('verifies webhook with standard Request object', async () => {
+ const mockRequest = new Request('https://clerk.com/webhooks', {
+ method: 'POST',
+ body: mockBody,
+ headers: new Headers(mockHeaders),
+ }) as unknown as RequestLike;
+
+ const result = await verifyWebhook(mockRequest);
+ expect(result).toEqual(mockSuccessResponse);
+ });
+ });
+
+ describe('with NextApiRequest', () => {
+ it('verifies webhook with NextApiRequest object', async () => {
+ const mockNextApiRequest = {
+ method: 'POST',
+ url: '/webhooks',
+ headers: {
+ ...mockHeaders,
+ host: 'clerk.com',
+ 'x-forwarded-proto': 'https',
+ },
+ body: JSON.parse(mockBody),
+ query: {},
+ cookies: {},
+ env: {},
+ aborted: false,
+ } as unknown as NextApiRequest;
+
+ const result = await verifyWebhook(mockNextApiRequest);
+ expect(result).toEqual(mockSuccessResponse);
+ });
+
+ it('throws error when headers are missing', async () => {
+ const mockNextApiRequest = {
+ method: 'POST',
+ url: '/webhooks',
+ headers: {
+ host: 'clerk.com',
+ 'x-forwarded-proto': 'https',
+ },
+ body: JSON.parse(mockBody),
+ query: {},
+ cookies: {},
+ env: {},
+ aborted: false,
+ } as unknown as NextApiRequest;
+
+ await expect(verifyWebhook(mockNextApiRequest)).rejects.toThrow(mockError);
+ });
+ });
+});

packages/nextjs/src/webhooks.ts

@@ -1 +1,81 @@
+/* eslint-disable import/export */
+import type { VerifyWebhookOptions } from '@clerk/backend/webhooks';
+import { verifyWebhook as verifyWebhookBase } from '@clerk/backend/webhooks';
+
+import { getHeader, isNextRequest, isRequestWebAPI } from './server/headers-utils';
+import type { RequestLike } from './server/types';
+// Ordering of exports matter here since
+// we're overriding the base verifyWebhook
 export * from '@clerk/backend/webhooks';
+
+const SVIX_ID_HEADER = 'svix-id';
+const SVIX_TIMESTAMP_HEADER = 'svix-timestamp';
+const SVIX_SIGNATURE_HEADER = 'svix-signature';
+
+/**
+ * Verifies the authenticity of a webhook request using Svix.
+ *
+ * @param request - The incoming webhook request object
+ * @param options - Optional configuration object
+ * @param options.signingSecret - Custom signing secret. If not provided, falls back to CLERK_WEBHOOK_SIGNING_SECRET env variable
+ * @throws Will throw an error if the webhook signature verification fails
+ * @returns A promise that resolves to the verified webhook event data
+ *
+ * @example
+ * ```typescript
+ * import { verifyWebhook } from '@clerk/nextjs/webhooks';
+ *
+ * export async function POST(req: Request) {
+ * try {
+ * const evt = await verifyWebhook(req);
+ *
+ * // Access the event data
+ * const { id } = evt.data;
+ * const eventType = evt.type;
+ *
+ * // Handle specific event types
+ * if (evt.type === 'user.created') {
+ * console.log('New user created:', evt.data.id);
+ * // Handle user creation
+ * }
+ *
+ * return new Response('Success', { status: 200 });
+ * } catch (err) {
+ * console.error('Webhook verification failed:', err);
+ * return new Response('Webhook verification failed', { status: 400 });
+ * }
+ * }
+ * ```
+ */
+export async function verifyWebhook(request: RequestLike, options?: VerifyWebhookOptions) {
+ if (isNextRequest(request) || isRequestWebAPI(request)) {
+ return verifyWebhookBase(request, options);
+ }
+
+ const webRequest = nextApiRequestToWebRequest(request);
+ return verifyWebhookBase(webRequest, options);
+}
+
+function nextApiRequestToWebRequest(req: RequestLike): Request {
+ const headers = new Headers();
+ const svixId = getHeader(req, SVIX_ID_HEADER) || '';
+ const svixTimestamp = getHeader(req, SVIX_TIMESTAMP_HEADER) || '';
+ const svixSignature = getHeader(req, SVIX_SIGNATURE_HEADER) || '';
+
+ headers.set(SVIX_ID_HEADER, svixId);
+ headers.set(SVIX_TIMESTAMP_HEADER, svixTimestamp);
+ headers.set(SVIX_SIGNATURE_HEADER, svixSignature);
+
+ // Create a dummy URL to make a Request object
+ const protocol = getHeader(req, 'x-forwarded-proto') || 'http';
+ const host = getHeader(req, 'x-forwarded-host') || 'clerk-dummy';
+ const dummyOriginReqUrl = new URL(req.url || '', `${protocol}://${host}`);
+
+ const body = 'body' in req && req.body ? JSON.stringify(req.body) : undefined;
+
+ return new Request(dummyOriginReqUrl, {
+ method: req.method,
+ headers,
+ body,
+ });
+}

.changeset/free-actors-prove.md

@@ -0,0 +1,43 @@
+---
+'@clerk/nextjs': patch
+---
+
+Add support for webhook verification with Next.js Pages Router.
+
+```ts
+// Next.js Pages Router
+import type { NextApiRequest, NextApiResponse } from 'next'
+import { verifyWebhook } from '@clerk/nextjs/webhooks';
+
+export const config = {
+ api: {
+ bodyParser: false,
+ },
+}
+
+export default async function handler(
+ req: NextApiRequest,
+ res: NextApiResponse
+) {
+ try {
+ const evt = await verifyWebhook(req);
+ // Handle webhook event
+ res.status(200).json({ received: true });
+ } catch (err) {
+ res.status(400).json({ error: 'Webhook verification failed' });
+ }
+}
+
+// tRPC
+import { verifyWebhook } from '@clerk/nextjs/webhooks';
+
+const webhookRouter = router({
+ webhook: publicProcedure
+ .input(/** schema */)
+ .mutation(async ({ ctx }) => {
+ const evt = await verifyWebhook(ctx.req);
+ // Handle webhook event
+ return { received: true };
+ }),
+});
+```

packages/nextjs/src/__tests__/webhooks.test.ts

@@ -0,0 +1,94 @@
+import type { NextApiRequest } from 'next';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type { RequestLike } from '../server/types';
+import { verifyWebhook } from '../webhooks';
+
+const mockSuccessResponse = {
+ type: 'user.created',
+ data: { id: 'user_123' },
+ object: 'event',
+} as any;
+
+const mockError = new Error('Missing required Svix headers: svix-id, svix-timestamp, svix-signature');
+
+vi.mock('@clerk/backend/webhooks', () => ({
+ verifyWebhook: vi.fn().mockImplementation((request: Request) => {
+ const svixId = request.headers.get('svix-id');
+ const svixTimestamp = request.headers.get('svix-timestamp');
+ const svixSignature = request.headers.get('svix-signature');
+
+ if (!svixId || !svixTimestamp || !svixSignature) {
+ throw mockError;
+ }
+
+ return mockSuccessResponse;
+ }),
+}));
+
+describe('verifyWebhook', () => {
+ const mockSecret = 'test_signing_secret';
+ const mockBody = JSON.stringify(mockSuccessResponse);
+ const mockHeaders = {
+ 'svix-id': 'msg_123',
+ 'svix-timestamp': '1614265330',
+ 'svix-signature': 'v1,test_signature',
+ };
+
+ beforeEach(() => {
+ process.env.CLERK_WEBHOOK_SIGNING_SECRET = mockSecret;
+ });
+
+ describe('with standard Request', () => {
+ it('verifies webhook with standard Request object', async () => {
+ const mockRequest = new Request('https://clerk.com/webhooks', {
+ method: 'POST',
+ body: mockBody,
+ headers: new Headers(mockHeaders),
+ }) as unknown as RequestLike;
+
+ const result = await verifyWebhook(mockRequest);
+ expect(result).toEqual(mockSuccessResponse);
+ });
+ });
+
+ describe('with NextApiRequest', () => {
+ it('verifies webhook with NextApiRequest object', async () => {
+ const mockNextApiRequest = {
+ method: 'POST',
+ url: '/webhooks',
+ headers: {
+ ...mockHeaders,
+ host: 'clerk.com',
+ 'x-forwarded-proto': 'https',
+ },
+ body: JSON.parse(mockBody),
+ query: {},
+ cookies: {},
+ env: {},
+ aborted: false,
+ } as unknown as NextApiRequest;
+
+ const result = await verifyWebhook(mockNextApiRequest);
+ expect(result).toEqual(mockSuccessResponse);
+ });
+
+ it('throws error when headers are missing', async () => {
+ const mockNextApiRequest = {
+ method: 'POST',
+ url: '/webhooks',
+ headers: {
+ host: 'clerk.com',
+ 'x-forwarded-proto': 'https',
+ },
+ body: JSON.parse(mockBody),
+ query: {},
+ cookies: {},
+ env: {},
+ aborted: false,
+ } as unknown as NextApiRequest;
+
+ await expect(verifyWebhook(mockNextApiRequest)).rejects.toThrow(mockError);
+ });
+ });
+});

packages/nextjs/src/webhooks.ts

@@ -1 +1,81 @@
+/* eslint-disable import/export */
+import type { VerifyWebhookOptions } from '@clerk/backend/webhooks';
+import { verifyWebhook as verifyWebhookBase } from '@clerk/backend/webhooks';
+
+import { getHeader, isNextRequest, isRequestWebAPI } from './server/headers-utils';
+import type { RequestLike } from './server/types';
+// Ordering of exports matter here since
+// we're overriding the base verifyWebhook
 export * from '@clerk/backend/webhooks';
+
+const SVIX_ID_HEADER = 'svix-id';
+const SVIX_TIMESTAMP_HEADER = 'svix-timestamp';
+const SVIX_SIGNATURE_HEADER = 'svix-signature';
+
+/**
+ * Verifies the authenticity of a webhook request using Svix.
+ *
+ * @param request - The incoming webhook request object
+ * @param options - Optional configuration object
+ * @param options.signingSecret - Custom signing secret. If not provided, falls back to CLERK_WEBHOOK_SIGNING_SECRET env variable
+ * @throws Will throw an error if the webhook signature verification fails
+ * @returns A promise that resolves to the verified webhook event data
+ *
+ * @example
+ * ```typescript
+ * import { verifyWebhook } from '@clerk/nextjs/webhooks';
+ *
+ * export async function POST(req: Request) {
+ * try {
+ * const evt = await verifyWebhook(req);
+ *
+ * // Access the event data
+ * const { id } = evt.data;
+ * const eventType = evt.type;
+ *
+ * // Handle specific event types
+ * if (evt.type === 'user.created') {
+ * console.log('New user created:', evt.data.id);
+ * // Handle user creation
+ * }
+ *
+ * return new Response('Success', { status: 200 });
+ * } catch (err) {
+ * console.error('Webhook verification failed:', err);
+ * return new Response('Webhook verification failed', { status: 400 });
+ * }
+ * }
+ * ```
+ */
+export async function verifyWebhook(request: RequestLike, options?: VerifyWebhookOptions) {
+ if (isNextRequest(request) || isRequestWebAPI(request)) {
+ return verifyWebhookBase(request, options);
+ }
+
+ const webRequest = nextApiRequestToWebRequest(request);
+ return verifyWebhookBase(webRequest, options);
+}
+
+function nextApiRequestToWebRequest(req: RequestLike): Request {
+ const headers = new Headers();
+ const svixId = getHeader(req, SVIX_ID_HEADER) || '';
+ const svixTimestamp = getHeader(req, SVIX_TIMESTAMP_HEADER) || '';
+ const svixSignature = getHeader(req, SVIX_SIGNATURE_HEADER) || '';
+
+ headers.set(SVIX_ID_HEADER, svixId);
+ headers.set(SVIX_TIMESTAMP_HEADER, svixTimestamp);
+ headers.set(SVIX_SIGNATURE_HEADER, svixSignature);
+
+ // Create a dummy URL to make a Request object
+ const protocol = getHeader(req, 'x-forwarded-proto') || 'http';
+ const host = getHeader(req, 'x-forwarded-host') || 'clerk-dummy';
+ const dummyOriginReqUrl = new URL(req.url || '', `${protocol}://${host}`);
+
+ const body = 'body' in req && req.body ? JSON.stringify(req.body) : undefined;
+
+ return new Request(dummyOriginReqUrl, {
+ method: req.method,
+ headers,
+ body,
+ });
+}

.changeset/free-actors-prove.md

@@ -0,0 +1,43 @@
+---
+'@clerk/nextjs': patch
+---
+
+Add support for webhook verification with Next.js Pages Router.
+
+```ts
+// Next.js Pages Router
+import type { NextApiRequest, NextApiResponse } from 'next'
+import { verifyWebhook } from '@clerk/nextjs/webhooks';
+
+export const config = {
+ api: {
+ bodyParser: false,
+ },
+}
+
+export default async function handler(
+ req: NextApiRequest,
+ res: NextApiResponse
+) {
+ try {
+ const evt = await verifyWebhook(req);
+ // Handle webhook event
+ res.status(200).json({ received: true });
+ } catch (err) {
+ res.status(400).json({ error: 'Webhook verification failed' });
+ }
+}
+
+// tRPC
+import { verifyWebhook } from '@clerk/nextjs/webhooks';
+
+const webhookRouter = router({
+ webhook: publicProcedure
+ .input(/** schema */)
+ .mutation(async ({ ctx }) => {
+ const evt = await verifyWebhook(ctx.req);
+ // Handle webhook event
+ return { received: true };
+ }),
+});
+```

packages/nextjs/src/__tests__/webhooks.test.ts

@@ -0,0 +1,94 @@
+import type { NextApiRequest } from 'next';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type { RequestLike } from '../server/types';
+import { verifyWebhook } from '../webhooks';
+
+const mockSuccessResponse = {
+ type: 'user.created',
+ data: { id: 'user_123' },
+ object: 'event',
+} as any;
+
+const mockError = new Error('Missing required Svix headers: svix-id, svix-timestamp, svix-signature');
+
+vi.mock('@clerk/backend/webhooks', () => ({
+ verifyWebhook: vi.fn().mockImplementation((request: Request) => {
+ const svixId = request.headers.get('svix-id');
+ const svixTimestamp = request.headers.get('svix-timestamp');
+ const svixSignature = request.headers.get('svix-signature');
+
+ if (!svixId || !svixTimestamp || !svixSignature) {
+ throw mockError;
+ }
+
+ return mockSuccessResponse;
+ }),
+}));
+
+describe('verifyWebhook', () => {
+ const mockSecret = 'test_signing_secret';
+ const mockBody = JSON.stringify(mockSuccessResponse);
+ const mockHeaders = {
+ 'svix-id': 'msg_123',
+ 'svix-timestamp': '1614265330',
+ 'svix-signature': 'v1,test_signature',
+ };
+
+ beforeEach(() => {
+ process.env.CLERK_WEBHOOK_SIGNING_SECRET = mockSecret;
+ });
+
+ describe('with standard Request', () => {
+ it('verifies webhook with standard Request object', async () => {
+ const mockRequest = new Request('https://clerk.com/webhooks', {
+ method: 'POST',
+ body: mockBody,
+ headers: new Headers(mockHeaders),
+ }) as unknown as RequestLike;
+
+ const result = await verifyWebhook(mockRequest);
+ expect(result).toEqual(mockSuccessResponse);
+ });
+ });
+
+ describe('with NextApiRequest', () => {
+ it('verifies webhook with NextApiRequest object', async () => {
+ const mockNextApiRequest = {
+ method: 'POST',
+ url: '/webhooks',
+ headers: {
+ ...mockHeaders,
+ host: 'clerk.com',
+ 'x-forwarded-proto': 'https',
+ },
+ body: JSON.parse(mockBody),
+ query: {},
+ cookies: {},
+ env: {},
+ aborted: false,
+ } as unknown as NextApiRequest;
+
+ const result = await verifyWebhook(mockNextApiRequest);
+ expect(result).toEqual(mockSuccessResponse);
+ });
+
+ it('throws error when headers are missing', async () => {
+ const mockNextApiRequest = {
+ method: 'POST',
+ url: '/webhooks',
+ headers: {
+ host: 'clerk.com',
+ 'x-forwarded-proto': 'https',
+ },
+ body: JSON.parse(mockBody),
+ query: {},
+ cookies: {},
+ env: {},
+ aborted: false,
+ } as unknown as NextApiRequest;
+
+ await expect(verifyWebhook(mockNextApiRequest)).rejects.toThrow(mockError);
+ });
+ });
+});

packages/nextjs/src/webhooks.ts

@@ -1 +1,81 @@
+/* eslint-disable import/export */
+import type { VerifyWebhookOptions } from '@clerk/backend/webhooks';
+import { verifyWebhook as verifyWebhookBase } from '@clerk/backend/webhooks';
+
+import { getHeader, isNextRequest, isRequestWebAPI } from './server/headers-utils';
+import type { RequestLike } from './server/types';
+// Ordering of exports matter here since
+// we're overriding the base verifyWebhook
 export * from '@clerk/backend/webhooks';
+
+const SVIX_ID_HEADER = 'svix-id';
+const SVIX_TIMESTAMP_HEADER = 'svix-timestamp';
+const SVIX_SIGNATURE_HEADER = 'svix-signature';
+
+/**
+ * Verifies the authenticity of a webhook request using Svix.
+ *
+ * @param request - The incoming webhook request object
+ * @param options - Optional configuration object
+ * @param options.signingSecret - Custom signing secret. If not provided, falls back to CLERK_WEBHOOK_SIGNING_SECRET env variable
+ * @throws Will throw an error if the webhook signature verification fails
+ * @returns A promise that resolves to the verified webhook event data
+ *
+ * @example
+ * ```typescript
+ * import { verifyWebhook } from '@clerk/nextjs/webhooks';
+ *
+ * export async function POST(req: Request) {
+ * try {
+ * const evt = await verifyWebhook(req);
+ *
+ * // Access the event data
+ * const { id } = evt.data;
+ * const eventType = evt.type;
+ *
+ * // Handle specific event types
+ * if (evt.type === 'user.created') {
+ * console.log('New user created:', evt.data.id);
+ * // Handle user creation
+ * }
+ *
+ * return new Response('Success', { status: 200 });
+ * } catch (err) {
+ * console.error('Webhook verification failed:', err);
+ * return new Response('Webhook verification failed', { status: 400 });
+ * }
+ * }
+ * ```
+ */
+export async function verifyWebhook(request: RequestLike, options?: VerifyWebhookOptions) {
+ if (isNextRequest(request) || isRequestWebAPI(request)) {
+ return verifyWebhookBase(request, options);
+ }
+
+ const webRequest = nextApiRequestToWebRequest(request);
+ return verifyWebhookBase(webRequest, options);
+}
+
+function nextApiRequestToWebRequest(req: RequestLike): Request {
+ const headers = new Headers();
+ const svixId = getHeader(req, SVIX_ID_HEADER) || '';
+ const svixTimestamp = getHeader(req, SVIX_TIMESTAMP_HEADER) || '';
+ const svixSignature = getHeader(req, SVIX_SIGNATURE_HEADER) || '';
+
+ headers.set(SVIX_ID_HEADER, svixId);
+ headers.set(SVIX_TIMESTAMP_HEADER, svixTimestamp);
+ headers.set(SVIX_SIGNATURE_HEADER, svixSignature);
+
+ // Create a dummy URL to make a Request object
+ const protocol = getHeader(req, 'x-forwarded-proto') || 'http';
+ const host = getHeader(req, 'x-forwarded-host') || 'clerk-dummy';
+ const dummyOriginReqUrl = new URL(req.url || '', `${protocol}://${host}`);
+
+ const body = 'body' in req && req.body ? JSON.stringify(req.body) : undefined;
+
+ return new Request(dummyOriginReqUrl, {
+ method: req.method,
+ headers,
+ body,
+ });
+}

.changeset/free-actors-prove.md

@@ -0,0 +1,43 @@
+---
+'@clerk/nextjs': patch
+---
+
+Add support for webhook verification with Next.js Pages Router.
+
+```ts
+// Next.js Pages Router
+import type { NextApiRequest, NextApiResponse } from 'next'
+import { verifyWebhook } from '@clerk/nextjs/webhooks';
+
+export const config = {
+ api: {
+ bodyParser: false,
+ },
+}
+
+export default async function handler(
+ req: NextApiRequest,
+ res: NextApiResponse
+) {
+ try {
+ const evt = await verifyWebhook(req);
+ // Handle webhook event
+ res.status(200).json({ received: true });
+ } catch (err) {
+ res.status(400).json({ error: 'Webhook verification failed' });
+ }
+}
+
+// tRPC
+import { verifyWebhook } from '@clerk/nextjs/webhooks';
+
+const webhookRouter = router({
+ webhook: publicProcedure
+ .input(/** schema */)
+ .mutation(async ({ ctx }) => {
+ const evt = await verifyWebhook(ctx.req);
+ // Handle webhook event
+ return { received: true };
+ }),
+});
+```

packages/nextjs/src/__tests__/webhooks.test.ts

@@ -0,0 +1,94 @@
+import type { NextApiRequest } from 'next';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type { RequestLike } from '../server/types';
+import { verifyWebhook } from '../webhooks';
+
+const mockSuccessResponse = {
+ type: 'user.created',
+ data: { id: 'user_123' },
+ object: 'event',
+} as any;
+
+const mockError = new Error('Missing required Svix headers: svix-id, svix-timestamp, svix-signature');
+
+vi.mock('@clerk/backend/webhooks', () => ({
+ verifyWebhook: vi.fn().mockImplementation((request: Request) => {
+ const svixId = request.headers.get('svix-id');
+ const svixTimestamp = request.headers.get('svix-timestamp');
+ const svixSignature = request.headers.get('svix-signature');
+
+ if (!svixId || !svixTimestamp || !svixSignature) {
+ throw mockError;
+ }
+
+ return mockSuccessResponse;
+ }),
+}));
+
+describe('verifyWebhook', () => {
+ const mockSecret = 'test_signing_secret';
+ const mockBody = JSON.stringify(mockSuccessResponse);
+ const mockHeaders = {
+ 'svix-id': 'msg_123',
+ 'svix-timestamp': '1614265330',
+ 'svix-signature': 'v1,test_signature',
+ };
+
+ beforeEach(() => {
+ process.env.CLERK_WEBHOOK_SIGNING_SECRET = mockSecret;
+ });
+
+ describe('with standard Request', () => {
+ it('verifies webhook with standard Request object', async () => {
+ const mockRequest = new Request('https://clerk.com/webhooks', {
+ method: 'POST',
+ body: mockBody,
+ headers: new Headers(mockHeaders),
+ }) as unknown as RequestLike;
+
+ const result = await verifyWebhook(mockRequest);
+ expect(result).toEqual(mockSuccessResponse);
+ });
+ });
+
+ describe('with NextApiRequest', () => {
+ it('verifies webhook with NextApiRequest object', async () => {
+ const mockNextApiRequest = {
+ method: 'POST',
+ url: '/webhooks',
+ headers: {
+ ...mockHeaders,
+ host: 'clerk.com',
+ 'x-forwarded-proto': 'https',
+ },
+ body: JSON.parse(mockBody),
+ query: {},
+ cookies: {},
+ env: {},
+ aborted: false,
+ } as unknown as NextApiRequest;
+
+ const result = await verifyWebhook(mockNextApiRequest);
+ expect(result).toEqual(mockSuccessResponse);
+ });
+
+ it('throws error when headers are missing', async () => {
+ const mockNextApiRequest = {
+ method: 'POST',
+ url: '/webhooks',
+ headers: {
+ host: 'clerk.com',
+ 'x-forwarded-proto': 'https',
+ },
+ body: JSON.parse(mockBody),
+ query: {},
+ cookies: {},
+ env: {},
+ aborted: false,
+ } as unknown as NextApiRequest;
+
+ await expect(verifyWebhook(mockNextApiRequest)).rejects.toThrow(mockError);
+ });
+ });
+});

packages/nextjs/src/webhooks.ts

@@ -1 +1,81 @@
+/* eslint-disable import/export */
+import type { VerifyWebhookOptions } from '@clerk/backend/webhooks';
+import { verifyWebhook as verifyWebhookBase } from '@clerk/backend/webhooks';
+
+import { getHeader, isNextRequest, isRequestWebAPI } from './server/headers-utils';
+import type { RequestLike } from './server/types';
+// Ordering of exports matter here since
+// we're overriding the base verifyWebhook
 export * from '@clerk/backend/webhooks';
+
+const SVIX_ID_HEADER = 'svix-id';
+const SVIX_TIMESTAMP_HEADER = 'svix-timestamp';
+const SVIX_SIGNATURE_HEADER = 'svix-signature';
+
+/**
+ * Verifies the authenticity of a webhook request using Svix.
+ *
+ * @param request - The incoming webhook request object
+ * @param options - Optional configuration object
+ * @param options.signingSecret - Custom signing secret. If not provided, falls back to CLERK_WEBHOOK_SIGNING_SECRET env variable
+ * @throws Will throw an error if the webhook signature verification fails
+ * @returns A promise that resolves to the verified webhook event data
+ *
+ * @example
+ * ```typescript
+ * import { verifyWebhook } from '@clerk/nextjs/webhooks';
+ *
+ * export async function POST(req: Request) {
+ * try {
+ * const evt = await verifyWebhook(req);
+ *
+ * // Access the event data
+ * const { id } = evt.data;
+ * const eventType = evt.type;
+ *
+ * // Handle specific event types
+ * if (evt.type === 'user.created') {
+ * console.log('New user created:', evt.data.id);
+ * // Handle user creation
+ * }
+ *
+ * return new Response('Success', { status: 200 });
+ * } catch (err) {
+ * console.error('Webhook verification failed:', err);
+ * return new Response('Webhook verification failed', { status: 400 });
+ * }
+ * }
+ * ```
+ */
+export async function verifyWebhook(request: RequestLike, options?: VerifyWebhookOptions) {
+ if (isNextRequest(request) || isRequestWebAPI(request)) {
+ return verifyWebhookBase(request, options);
+ }
+
+ const webRequest = nextApiRequestToWebRequest(request);
+ return verifyWebhookBase(webRequest, options);
+}
+
+function nextApiRequestToWebRequest(req: RequestLike): Request {
+ const headers = new Headers();
+ const svixId = getHeader(req, SVIX_ID_HEADER) || '';
+ const svixTimestamp = getHeader(req, SVIX_TIMESTAMP_HEADER) || '';
+ const svixSignature = getHeader(req, SVIX_SIGNATURE_HEADER) || '';
+
+ headers.set(SVIX_ID_HEADER, svixId);
+ headers.set(SVIX_TIMESTAMP_HEADER, svixTimestamp);
+ headers.set(SVIX_SIGNATURE_HEADER, svixSignature);
+
+ // Create a dummy URL to make a Request object
+ const protocol = getHeader(req, 'x-forwarded-proto') || 'http';
+ const host = getHeader(req, 'x-forwarded-host') || 'clerk-dummy';
+ const dummyOriginReqUrl = new URL(req.url || '', `${protocol}://${host}`);
+
+ const body = 'body' in req && req.body ? JSON.stringify(req.body) : undefined;
+
+ return new Request(dummyOriginReqUrl, {
+ method: req.method,
+ headers,
+ body,
+ });
+}

.changeset/free-actors-prove.md

@@ -0,0 +1,43 @@
+---
+'@clerk/nextjs': patch
+---
+
+Add support for webhook verification with Next.js Pages Router.
+
+```ts
+// Next.js Pages Router
+import type { NextApiRequest, NextApiResponse } from 'next'
+import { verifyWebhook } from '@clerk/nextjs/webhooks';
+
+export const config = {
+ api: {
+ bodyParser: false,
+ },
+}
+
+export default async function handler(
+ req: NextApiRequest,
+ res: NextApiResponse
+) {
+ try {
+ const evt = await verifyWebhook(req);
+ // Handle webhook event
+ res.status(200).json({ received: true });
+ } catch (err) {
+ res.status(400).json({ error: 'Webhook verification failed' });
+ }
+}
+
+// tRPC
+import { verifyWebhook } from '@clerk/nextjs/webhooks';
+
+const webhookRouter = router({
+ webhook: publicProcedure
+ .input(/** schema */)
+ .mutation(async ({ ctx }) => {
+ const evt = await verifyWebhook(ctx.req);
+ // Handle webhook event
+ return { received: true };
+ }),
+});
+```

packages/nextjs/src/__tests__/webhooks.test.ts

@@ -0,0 +1,94 @@
+import type { NextApiRequest } from 'next';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type { RequestLike } from '../server/types';
+import { verifyWebhook } from '../webhooks';
+
+const mockSuccessResponse = {
+ type: 'user.created',
+ data: { id: 'user_123' },
+ object: 'event',
+} as any;
+
+const mockError = new Error('Missing required Svix headers: svix-id, svix-timestamp, svix-signature');
+
+vi.mock('@clerk/backend/webhooks', () => ({
+ verifyWebhook: vi.fn().mockImplementation((request: Request) => {
+ const svixId = request.headers.get('svix-id');
+ const svixTimestamp = request.headers.get('svix-timestamp');
+ const svixSignature = request.headers.get('svix-signature');
+
+ if (!svixId || !svixTimestamp || !svixSignature) {
+ throw mockError;
+ }
+
+ return mockSuccessResponse;
+ }),
+}));
+
+describe('verifyWebhook', () => {
+ const mockSecret = 'test_signing_secret';
+ const mockBody = JSON.stringify(mockSuccessResponse);
+ const mockHeaders = {
+ 'svix-id': 'msg_123',
+ 'svix-timestamp': '1614265330',
+ 'svix-signature': 'v1,test_signature',
+ };
+
+ beforeEach(() => {
+ process.env.CLERK_WEBHOOK_SIGNING_SECRET = mockSecret;
+ });
+
+ describe('with standard Request', () => {
+ it('verifies webhook with standard Request object', async () => {
+ const mockRequest = new Request('https://clerk.com/webhooks', {
+ method: 'POST',
+ body: mockBody,
+ headers: new Headers(mockHeaders),
+ }) as unknown as RequestLike;
+
+ const result = await verifyWebhook(mockRequest);
+ expect(result).toEqual(mockSuccessResponse);
+ });
+ });
+
+ describe('with NextApiRequest', () => {
+ it('verifies webhook with NextApiRequest object', async () => {
+ const mockNextApiRequest = {
+ method: 'POST',
+ url: '/webhooks',
+ headers: {
+ ...mockHeaders,
+ host: 'clerk.com',
+ 'x-forwarded-proto': 'https',
+ },
+ body: JSON.parse(mockBody),
+ query: {},
+ cookies: {},
+ env: {},
+ aborted: false,
+ } as unknown as NextApiRequest;
+
+ const result = await verifyWebhook(mockNextApiRequest);
+ expect(result).toEqual(mockSuccessResponse);
+ });
+
+ it('throws error when headers are missing', async () => {
+ const mockNextApiRequest = {
+ method: 'POST',
+ url: '/webhooks',
+ headers: {
+ host: 'clerk.com',
+ 'x-forwarded-proto': 'https',
+ },
+ body: JSON.parse(mockBody),
+ query: {},
+ cookies: {},
+ env: {},
+ aborted: false,
+ } as unknown as NextApiRequest;
+
+ await expect(verifyWebhook(mockNextApiRequest)).rejects.toThrow(mockError);
+ });
+ });
+});

packages/nextjs/src/webhooks.ts

@@ -1 +1,81 @@
+/* eslint-disable import/export */
+import type { VerifyWebhookOptions } from '@clerk/backend/webhooks';
+import { verifyWebhook as verifyWebhookBase } from '@clerk/backend/webhooks';
+
+import { getHeader, isNextRequest, isRequestWebAPI } from './server/headers-utils';
+import type { RequestLike } from './server/types';
+// Ordering of exports matter here since
+// we're overriding the base verifyWebhook
 export * from '@clerk/backend/webhooks';
+
+const SVIX_ID_HEADER = 'svix-id';
+const SVIX_TIMESTAMP_HEADER = 'svix-timestamp';
+const SVIX_SIGNATURE_HEADER = 'svix-signature';
+
+/**
+ * Verifies the authenticity of a webhook request using Svix.
+ *
+ * @param request - The incoming webhook request object
+ * @param options - Optional configuration object
+ * @param options.signingSecret - Custom signing secret. If not provided, falls back to CLERK_WEBHOOK_SIGNING_SECRET env variable
+ * @throws Will throw an error if the webhook signature verification fails
+ * @returns A promise that resolves to the verified webhook event data
+ *
+ * @example
+ * ```typescript
+ * import { verifyWebhook } from '@clerk/nextjs/webhooks';
+ *
+ * export async function POST(req: Request) {
+ * try {
+ * const evt = await verifyWebhook(req);
+ *
+ * // Access the event data
+ * const { id } = evt.data;
+ * const eventType = evt.type;
+ *
+ * // Handle specific event types
+ * if (evt.type === 'user.created') {
+ * console.log('New user created:', evt.data.id);
+ * // Handle user creation
+ * }
+ *
+ * return new Response('Success', { status: 200 });
+ * } catch (err) {
+ * console.error('Webhook verification failed:', err);
+ * return new Response('Webhook verification failed', { status: 400 });
+ * }
+ * }
+ * ```
+ */
+export async function verifyWebhook(request: RequestLike, options?: VerifyWebhookOptions) {
+ if (isNextRequest(request) || isRequestWebAPI(request)) {
+ return verifyWebhookBase(request, options);
+ }
+
+ const webRequest = nextApiRequestToWebRequest(request);
+ return verifyWebhookBase(webRequest, options);
+}
+
+function nextApiRequestToWebRequest(req: RequestLike): Request {
+ const headers = new Headers();
+ const svixId = getHeader(req, SVIX_ID_HEADER) || '';
+ const svixTimestamp = getHeader(req, SVIX_TIMESTAMP_HEADER) || '';
+ const svixSignature = getHeader(req, SVIX_SIGNATURE_HEADER) || '';
+
+ headers.set(SVIX_ID_HEADER, svixId);
+ headers.set(SVIX_TIMESTAMP_HEADER, svixTimestamp);
+ headers.set(SVIX_SIGNATURE_HEADER, svixSignature);
+
+ // Create a dummy URL to make a Request object
+ const protocol = getHeader(req, 'x-forwarded-proto') || 'http';
+ const host = getHeader(req, 'x-forwarded-host') || 'clerk-dummy';
+ const dummyOriginReqUrl = new URL(req.url || '', `${protocol}://${host}`);
+
+ const body = 'body' in req && req.body ? JSON.stringify(req.body) : undefined;
+
+ return new Request(dummyOriginReqUrl, {
+ method: req.method,
+ headers,
+ body,
+ });
+}

.changeset/free-actors-prove.md

@@ -0,0 +1,43 @@
+---
+'@clerk/nextjs': patch
+---
+
+Add support for webhook verification with Next.js Pages Router.
+
+```ts
+// Next.js Pages Router
+import type { NextApiRequest, NextApiResponse } from 'next'
+import { verifyWebhook } from '@clerk/nextjs/webhooks';
+
+export const config = {
+ api: {
+ bodyParser: false,
+ },
+}
+
+export default async function handler(
+ req: NextApiRequest,
+ res: NextApiResponse
+) {
+ try {
+ const evt = await verifyWebhook(req);
+ // Handle webhook event
+ res.status(200).json({ received: true });
+ } catch (err) {
+ res.status(400).json({ error: 'Webhook verification failed' });
+ }
+}
+
+// tRPC
+import { verifyWebhook } from '@clerk/nextjs/webhooks';
+
+const webhookRouter = router({
+ webhook: publicProcedure
+ .input(/** schema */)
+ .mutation(async ({ ctx }) => {
+ const evt = await verifyWebhook(ctx.req);
+ // Handle webhook event
+ return { received: true };
+ }),
+});
+```

packages/nextjs/src/__tests__/webhooks.test.ts

@@ -0,0 +1,94 @@
+import type { NextApiRequest } from 'next';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type { RequestLike } from '../server/types';
+import { verifyWebhook } from '../webhooks';
+
+const mockSuccessResponse = {
+ type: 'user.created',
+ data: { id: 'user_123' },
+ object: 'event',
+} as any;
+
+const mockError = new Error('Missing required Svix headers: svix-id, svix-timestamp, svix-signature');
+
+vi.mock('@clerk/backend/webhooks', () => ({
+ verifyWebhook: vi.fn().mockImplementation((request: Request) => {
+ const svixId = request.headers.get('svix-id');
+ const svixTimestamp = request.headers.get('svix-timestamp');
+ const svixSignature = request.headers.get('svix-signature');
+
+ if (!svixId || !svixTimestamp || !svixSignature) {
+ throw mockError;
+ }
+
+ return mockSuccessResponse;
+ }),
+}));
+
+describe('verifyWebhook', () => {
+ const mockSecret = 'test_signing_secret';
+ const mockBody = JSON.stringify(mockSuccessResponse);
+ const mockHeaders = {
+ 'svix-id': 'msg_123',
+ 'svix-timestamp': '1614265330',
+ 'svix-signature': 'v1,test_signature',
+ };
+
+ beforeEach(() => {
+ process.env.CLERK_WEBHOOK_SIGNING_SECRET = mockSecret;
+ });
+
+ describe('with standard Request', () => {
+ it('verifies webhook with standard Request object', async () => {
+ const mockRequest = new Request('https://clerk.com/webhooks', {
+ method: 'POST',
+ body: mockBody,
+ headers: new Headers(mockHeaders),
+ }) as unknown as RequestLike;
+
+ const result = await verifyWebhook(mockRequest);
+ expect(result).toEqual(mockSuccessResponse);
+ });
+ });
+
+ describe('with NextApiRequest', () => {
+ it('verifies webhook with NextApiRequest object', async () => {
+ const mockNextApiRequest = {
+ method: 'POST',
+ url: '/webhooks',
+ headers: {
+ ...mockHeaders,
+ host: 'clerk.com',
+ 'x-forwarded-proto': 'https',
+ },
+ body: JSON.parse(mockBody),
+ query: {},
+ cookies: {},
+ env: {},
+ aborted: false,
+ } as unknown as NextApiRequest;
+
+ const result = await verifyWebhook(mockNextApiRequest);
+ expect(result).toEqual(mockSuccessResponse);
+ });
+
+ it('throws error when headers are missing', async () => {
+ const mockNextApiRequest = {
+ method: 'POST',
+ url: '/webhooks',
+ headers: {
+ host: 'clerk.com',
+ 'x-forwarded-proto': 'https',
+ },
+ body: JSON.parse(mockBody),
+ query: {},
+ cookies: {},
+ env: {},
+ aborted: false,
+ } as unknown as NextApiRequest;
+
+ await expect(verifyWebhook(mockNextApiRequest)).rejects.toThrow(mockError);
+ });
+ });
+});

packages/nextjs/src/webhooks.ts

@@ -1 +1,81 @@
+/* eslint-disable import/export */
+import type { VerifyWebhookOptions } from '@clerk/backend/webhooks';
+import { verifyWebhook as verifyWebhookBase } from '@clerk/backend/webhooks';
+
+import { getHeader, isNextRequest, isRequestWebAPI } from './server/headers-utils';
+import type { RequestLike } from './server/types';
+// Ordering of exports matter here since
+// we're overriding the base verifyWebhook
 export * from '@clerk/backend/webhooks';
+
+const SVIX_ID_HEADER = 'svix-id';
+const SVIX_TIMESTAMP_HEADER = 'svix-timestamp';
+const SVIX_SIGNATURE_HEADER = 'svix-signature';
+
+/**
+ * Verifies the authenticity of a webhook request using Svix.
+ *
+ * @param request - The incoming webhook request object
+ * @param options - Optional configuration object
+ * @param options.signingSecret - Custom signing secret. If not provided, falls back to CLERK_WEBHOOK_SIGNING_SECRET env variable
+ * @throws Will throw an error if the webhook signature verification fails
+ * @returns A promise that resolves to the verified webhook event data
+ *
+ * @example
+ * ```typescript
+ * import { verifyWebhook } from '@clerk/nextjs/webhooks';
+ *
+ * export async function POST(req: Request) {
+ * try {
+ * const evt = await verifyWebhook(req);
+ *
+ * // Access the event data
+ * const { id } = evt.data;
+ * const eventType = evt.type;
+ *
+ * // Handle specific event types
+ * if (evt.type === 'user.created') {
+ * console.log('New user created:', evt.data.id);
+ * // Handle user creation
+ * }
+ *
+ * return new Response('Success', { status: 200 });
+ * } catch (err) {
+ * console.error('Webhook verification failed:', err);
+ * return new Response('Webhook verification failed', { status: 400 });
+ * }
+ * }
+ * ```
+ */
+export async function verifyWebhook(request: RequestLike, options?: VerifyWebhookOptions) {
+ if (isNextRequest(request) || isRequestWebAPI(request)) {
+ return verifyWebhookBase(request, options);
+ }
+
+ const webRequest = nextApiRequestToWebRequest(request);
+ return verifyWebhookBase(webRequest, options);
+}
+
+function nextApiRequestToWebRequest(req: RequestLike): Request {
+ const headers = new Headers();
+ const svixId = getHeader(req, SVIX_ID_HEADER) || '';
+ const svixTimestamp = getHeader(req, SVIX_TIMESTAMP_HEADER) || '';
+ const svixSignature = getHeader(req, SVIX_SIGNATURE_HEADER) || '';
+
+ headers.set(SVIX_ID_HEADER, svixId);
+ headers.set(SVIX_TIMESTAMP_HEADER, svixTimestamp);
+ headers.set(SVIX_SIGNATURE_HEADER, svixSignature);
+
+ // Create a dummy URL to make a Request object
+ const protocol = getHeader(req, 'x-forwarded-proto') || 'http';
+ const host = getHeader(req, 'x-forwarded-host') || 'clerk-dummy';
+ const dummyOriginReqUrl = new URL(req.url || '', `${protocol}://${host}`);
+
+ const body = 'body' in req && req.body ? JSON.stringify(req.body) : undefined;
+
+ return new Request(dummyOriginReqUrl, {
+ method: req.method,
+ headers,
+ body,
+ });
+}

.changeset/free-actors-prove.md

@@ -0,0 +1,43 @@
+---
+'@clerk/nextjs': patch
+---
+
+Add support for webhook verification with Next.js Pages Router.
+
+```ts
+// Next.js Pages Router
+import type { NextApiRequest, NextApiResponse } from 'next'
+import { verifyWebhook } from '@clerk/nextjs/webhooks';
+
+export const config = {
+ api: {
+ bodyParser: false,
+ },
+}
+
+export default async function handler(
+ req: NextApiRequest,
+ res: NextApiResponse
+) {
+ try {
+ const evt = await verifyWebhook(req);
+ // Handle webhook event
+ res.status(200).json({ received: true });
+ } catch (err) {
+ res.status(400).json({ error: 'Webhook verification failed' });
+ }
+}
+
+// tRPC
+import { verifyWebhook } from '@clerk/nextjs/webhooks';
+
+const webhookRouter = router({
+ webhook: publicProcedure
+ .input(/** schema */)
+ .mutation(async ({ ctx }) => {
+ const evt = await verifyWebhook(ctx.req);
+ // Handle webhook event
+ return { received: true };
+ }),
+});
+```

packages/nextjs/src/__tests__/webhooks.test.ts

@@ -0,0 +1,94 @@
+import type { NextApiRequest } from 'next';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type { RequestLike } from '../server/types';
+import { verifyWebhook } from '../webhooks';
+
+const mockSuccessResponse = {
+ type: 'user.created',
+ data: { id: 'user_123' },
+ object: 'event',
+} as any;
+
+const mockError = new Error('Missing required Svix headers: svix-id, svix-timestamp, svix-signature');
+
+vi.mock('@clerk/backend/webhooks', () => ({
+ verifyWebhook: vi.fn().mockImplementation((request: Request) => {
+ const svixId = request.headers.get('svix-id');
+ const svixTimestamp = request.headers.get('svix-timestamp');
+ const svixSignature = request.headers.get('svix-signature');
+
+ if (!svixId || !svixTimestamp || !svixSignature) {
+ throw mockError;
+ }
+
+ return mockSuccessResponse;
+ }),
+}));
+
+describe('verifyWebhook', () => {
+ const mockSecret = 'test_signing_secret';
+ const mockBody = JSON.stringify(mockSuccessResponse);
+ const mockHeaders = {
+ 'svix-id': 'msg_123',
+ 'svix-timestamp': '1614265330',
+ 'svix-signature': 'v1,test_signature',
+ };
+
+ beforeEach(() => {
+ process.env.CLERK_WEBHOOK_SIGNING_SECRET = mockSecret;
+ });
+
+ describe('with standard Request', () => {
+ it('verifies webhook with standard Request object', async () => {
+ const mockRequest = new Request('https://clerk.com/webhooks', {
+ method: 'POST',
+ body: mockBody,
+ headers: new Headers(mockHeaders),
+ }) as unknown as RequestLike;
+
+ const result = await verifyWebhook(mockRequest);
+ expect(result).toEqual(mockSuccessResponse);
+ });
+ });
+
+ describe('with NextApiRequest', () => {
+ it('verifies webhook with NextApiRequest object', async () => {
+ const mockNextApiRequest = {
+ method: 'POST',
+ url: '/webhooks',
+ headers: {
+ ...mockHeaders,
+ host: 'clerk.com',
+ 'x-forwarded-proto': 'https',
+ },
+ body: JSON.parse(mockBody),
+ query: {},
+ cookies: {},
+ env: {},
+ aborted: false,
+ } as unknown as NextApiRequest;
+
+ const result = await verifyWebhook(mockNextApiRequest);
+ expect(result).toEqual(mockSuccessResponse);
+ });
+
+ it('throws error when headers are missing', async () => {
+ const mockNextApiRequest = {
+ method: 'POST',
+ url: '/webhooks',
+ headers: {
+ host: 'clerk.com',
+ 'x-forwarded-proto': 'https',
+ },
+ body: JSON.parse(mockBody),
+ query: {},
+ cookies: {},
+ env: {},
+ aborted: false,
+ } as unknown as NextApiRequest;
+
+ await expect(verifyWebhook(mockNextApiRequest)).rejects.toThrow(mockError);
+ });
+ });
+});

packages/nextjs/src/webhooks.ts

@@ -1 +1,81 @@
+/* eslint-disable import/export */
+import type { VerifyWebhookOptions } from '@clerk/backend/webhooks';
+import { verifyWebhook as verifyWebhookBase } from '@clerk/backend/webhooks';
+
+import { getHeader, isNextRequest, isRequestWebAPI } from './server/headers-utils';
+import type { RequestLike } from './server/types';
+// Ordering of exports matter here since
+// we're overriding the base verifyWebhook
 export * from '@clerk/backend/webhooks';
+
+const SVIX_ID_HEADER = 'svix-id';
+const SVIX_TIMESTAMP_HEADER = 'svix-timestamp';
+const SVIX_SIGNATURE_HEADER = 'svix-signature';
+
+/**
+ * Verifies the authenticity of a webhook request using Svix.
+ *
+ * @param request - The incoming webhook request object
+ * @param options - Optional configuration object
+ * @param options.signingSecret - Custom signing secret. If not provided, falls back to CLERK_WEBHOOK_SIGNING_SECRET env variable
+ * @throws Will throw an error if the webhook signature verification fails
+ * @returns A promise that resolves to the verified webhook event data
+ *
+ * @example
+ * ```typescript
+ * import { verifyWebhook } from '@clerk/nextjs/webhooks';
+ *
+ * export async function POST(req: Request) {
+ * try {
+ * const evt = await verifyWebhook(req);
+ *
+ * // Access the event data
+ * const { id } = evt.data;
+ * const eventType = evt.type;
+ *
+ * // Handle specific event types
+ * if (evt.type === 'user.created') {
+ * console.log('New user created:', evt.data.id);
+ * // Handle user creation
+ * }
+ *
+ * return new Response('Success', { status: 200 });
+ * } catch (err) {
+ * console.error('Webhook verification failed:', err);
+ * return new Response('Webhook verification failed', { status: 400 });
+ * }
+ * }
+ * ```
+ */
+export async function verifyWebhook(request: RequestLike, options?: VerifyWebhookOptions) {
+ if (isNextRequest(request) || isRequestWebAPI(request)) {
+ return verifyWebhookBase(request, options);
+ }
+
+ const webRequest = nextApiRequestToWebRequest(request);
+ return verifyWebhookBase(webRequest, options);
+}
+
+function nextApiRequestToWebRequest(req: RequestLike): Request {
+ const headers = new Headers();
+ const svixId = getHeader(req, SVIX_ID_HEADER) || '';
+ const svixTimestamp = getHeader(req, SVIX_TIMESTAMP_HEADER) || '';
+ const svixSignature = getHeader(req, SVIX_SIGNATURE_HEADER) || '';
+
+ headers.set(SVIX_ID_HEADER, svixId);
+ headers.set(SVIX_TIMESTAMP_HEADER, svixTimestamp);
+ headers.set(SVIX_SIGNATURE_HEADER, svixSignature);
+
+ // Create a dummy URL to make a Request object
+ const protocol = getHeader(req, 'x-forwarded-proto') || 'http';
+ const host = getHeader(req, 'x-forwarded-host') || 'clerk-dummy';
+ const dummyOriginReqUrl = new URL(req.url || '', `${protocol}://${host}`);
+
+ const body = 'body' in req && req.body ? JSON.stringify(req.body) : undefined;
+
+ return new Request(dummyOriginReqUrl, {
+ method: req.method,
+ headers,
+ body,
+ });
+}

.changeset/free-actors-prove.md

@@ -0,0 +1,43 @@
+---
+'@clerk/nextjs': patch
+---
+
+Add support for webhook verification with Next.js Pages Router.
+
+```ts
+// Next.js Pages Router
+import type { NextApiRequest, NextApiResponse } from 'next'
+import { verifyWebhook } from '@clerk/nextjs/webhooks';
+
+export const config = {
+ api: {
+ bodyParser: false,
+ },
+}
+
+export default async function handler(
+ req: NextApiRequest,
+ res: NextApiResponse
+) {
+ try {
+ const evt = await verifyWebhook(req);
+ // Handle webhook event
+ res.status(200).json({ received: true });
+ } catch (err) {
+ res.status(400).json({ error: 'Webhook verification failed' });
+ }
+}
+
+// tRPC
+import { verifyWebhook } from '@clerk/nextjs/webhooks';
+
+const webhookRouter = router({
+ webhook: publicProcedure
+ .input(/** schema */)
+ .mutation(async ({ ctx }) => {
+ const evt = await verifyWebhook(ctx.req);
+ // Handle webhook event
+ return { received: true };
+ }),
+});
+```

packages/nextjs/src/__tests__/webhooks.test.ts

@@ -0,0 +1,94 @@
+import type { NextApiRequest } from 'next';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type { RequestLike } from '../server/types';
+import { verifyWebhook } from '../webhooks';
+
+const mockSuccessResponse = {
+ type: 'user.created',
+ data: { id: 'user_123' },
+ object: 'event',
+} as any;
+
+const mockError = new Error('Missing required Svix headers: svix-id, svix-timestamp, svix-signature');
+
+vi.mock('@clerk/backend/webhooks', () => ({
+ verifyWebhook: vi.fn().mockImplementation((request: Request) => {
+ const svixId = request.headers.get('svix-id');
+ const svixTimestamp = request.headers.get('svix-timestamp');
+ const svixSignature = request.headers.get('svix-signature');
+
+ if (!svixId || !svixTimestamp || !svixSignature) {
+ throw mockError;
+ }
+
+ return mockSuccessResponse;
+ }),
+}));
+
+describe('verifyWebhook', () => {
+ const mockSecret = 'test_signing_secret';
+ const mockBody = JSON.stringify(mockSuccessResponse);
+ const mockHeaders = {
+ 'svix-id': 'msg_123',
+ 'svix-timestamp': '1614265330',
+ 'svix-signature': 'v1,test_signature',
+ };
+
+ beforeEach(() => {
+ process.env.CLERK_WEBHOOK_SIGNING_SECRET = mockSecret;
+ });
+
+ describe('with standard Request', () => {
+ it('verifies webhook with standard Request object', async () => {
+ const mockRequest = new Request('https://clerk.com/webhooks', {
+ method: 'POST',
+ body: mockBody,
+ headers: new Headers(mockHeaders),
+ }) as unknown as RequestLike;
+
+ const result = await verifyWebhook(mockRequest);
+ expect(result).toEqual(mockSuccessResponse);
+ });
+ });
+
+ describe('with NextApiRequest', () => {
+ it('verifies webhook with NextApiRequest object', async () => {
+ const mockNextApiRequest = {
+ method: 'POST',
+ url: '/webhooks',
+ headers: {
+ ...mockHeaders,
+ host: 'clerk.com',
+ 'x-forwarded-proto': 'https',
+ },
+ body: JSON.parse(mockBody),
+ query: {},
+ cookies: {},
+ env: {},
+ aborted: false,
+ } as unknown as NextApiRequest;
+
+ const result = await verifyWebhook(mockNextApiRequest);
+ expect(result).toEqual(mockSuccessResponse);
+ });
+
+ it('throws error when headers are missing', async () => {
+ const mockNextApiRequest = {
+ method: 'POST',
+ url: '/webhooks',
+ headers: {
+ host: 'clerk.com',
+ 'x-forwarded-proto': 'https',
+ },
+ body: JSON.parse(mockBody),
+ query: {},
+ cookies: {},
+ env: {},
+ aborted: false,
+ } as unknown as NextApiRequest;
+
+ await expect(verifyWebhook(mockNextApiRequest)).rejects.toThrow(mockError);
+ });
+ });
+});

packages/nextjs/src/webhooks.ts

@@ -1 +1,81 @@
+/* eslint-disable import/export */
+import type { VerifyWebhookOptions } from '@clerk/backend/webhooks';
+import { verifyWebhook as verifyWebhookBase } from '@clerk/backend/webhooks';
+
+import { getHeader, isNextRequest, isRequestWebAPI } from './server/headers-utils';
+import type { RequestLike } from './server/types';
+// Ordering of exports matter here since
+// we're overriding the base verifyWebhook
 export * from '@clerk/backend/webhooks';
+
+const SVIX_ID_HEADER = 'svix-id';
+const SVIX_TIMESTAMP_HEADER = 'svix-timestamp';
+const SVIX_SIGNATURE_HEADER = 'svix-signature';
+
+/**
+ * Verifies the authenticity of a webhook request using Svix.
+ *
+ * @param request - The incoming webhook request object
+ * @param options - Optional configuration object
+ * @param options.signingSecret - Custom signing secret. If not provided, falls back to CLERK_WEBHOOK_SIGNING_SECRET env variable
+ * @throws Will throw an error if the webhook signature verification fails
+ * @returns A promise that resolves to the verified webhook event data
+ *
+ * @example
+ * ```typescript
+ * import { verifyWebhook } from '@clerk/nextjs/webhooks';
+ *
+ * export async function POST(req: Request) {
+ * try {
+ * const evt = await verifyWebhook(req);
+ *
+ * // Access the event data
+ * const { id } = evt.data;
+ * const eventType = evt.type;
+ *
+ * // Handle specific event types
+ * if (evt.type === 'user.created') {
+ * console.log('New user created:', evt.data.id);
+ * // Handle user creation
+ * }
+ *
+ * return new Response('Success', { status: 200 });
+ * } catch (err) {
+ * console.error('Webhook verification failed:', err);
+ * return new Response('Webhook verification failed', { status: 400 });
+ * }
+ * }
+ * ```
+ */
+export async function verifyWebhook(request: RequestLike, options?: VerifyWebhookOptions) {
+ if (isNextRequest(request) || isRequestWebAPI(request)) {
+ return verifyWebhookBase(request, options);
+ }
+
+ const webRequest = nextApiRequestToWebRequest(request);
+ return verifyWebhookBase(webRequest, options);
+}
+
+function nextApiRequestToWebRequest(req: RequestLike): Request {
+ const headers = new Headers();
+ const svixId = getHeader(req, SVIX_ID_HEADER) || '';
+ const svixTimestamp = getHeader(req, SVIX_TIMESTAMP_HEADER) || '';
+ const svixSignature = getHeader(req, SVIX_SIGNATURE_HEADER) || '';
+
+ headers.set(SVIX_ID_HEADER, svixId);
+ headers.set(SVIX_TIMESTAMP_HEADER, svixTimestamp);
+ headers.set(SVIX_SIGNATURE_HEADER, svixSignature);
+
+ // Create a dummy URL to make a Request object
+ const protocol = getHeader(req, 'x-forwarded-proto') || 'http';
+ const host = getHeader(req, 'x-forwarded-host') || 'clerk-dummy';
+ const dummyOriginReqUrl = new URL(req.url || '', `${protocol}://${host}`);
+
+ const body = 'body' in req && req.body ? JSON.stringify(req.body) : undefined;
+
+ return new Request(dummyOriginReqUrl, {
+ method: req.method,
+ headers,
+ body,
+ });
+}