chore(backend): Refactor verifyWebhook() to use standardwebhooks library (#6252)

Author: brkalow

.changeset/chubby-tires-end.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': patch
+---
+
+Refactor webhook verification to use verification from the `standardwebhooks` package, which is what our underlying provider relies on.

packages/backend/package.json

@@ -111,6 +111,7 @@
     "@clerk/types": "workspace:^",
     "cookie": "1.0.2",
     "snakecase-keys": "8.0.1",
+    "standardwebhooks": "^1.0.0",
     "tslib": "catalog:repo"
   },
   "devDependencies": {

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

@@ -1,39 +1,45 @@
+import { Webhook } from 'standardwebhooks';
 import { beforeEach, describe, expect, it } from 'vitest';
 
 import { verifyWebhook } from '../webhooks';
 
 describe('verifyWebhook', () => {
-  const mockSecret = 'test_signing_secret';
+  const mockSecret = 'whsec_' + Buffer.from('test_signing_secret_32_chars_long').toString('base64');
   const mockBody = JSON.stringify({ type: 'user.created', data: { id: 'user_123' } });
 
   beforeEach(() => {
     process.env.CLERK_WEBHOOK_SIGNING_SECRET = mockSecret;
   });
 
+  // Helper function to create a valid signature with Standard Webhooks
+  const createValidSignature = (id: string, timestamp: string, body: string) => {
+    const webhook = new Webhook(mockSecret);
+    // Create a signature using the Standard Webhooks library
+    return webhook.sign(id, new Date(parseInt(timestamp) * 1000), body);
+  };
+
   it('throws when required headers are missing', async () => {
     const mockRequest = new Request('https://clerk.com/webhooks', {
       method: 'POST',
       body: mockBody,
       headers: new Headers({
-        // Missing svix-signature but with valid format for others
-        'svix-id': 'msg_123',
-        'svix-timestamp': '1614265330',
+        // Missing all required headers
       }),
     });
 
-    await expect(verifyWebhook(mockRequest)).rejects.toThrow('Missing required Svix headers: svix-signature');
+    await expect(verifyWebhook(mockRequest)).rejects.toThrow('Missing required webhook headers');
   });
 
   it('throws with all missing headers in error message', async () => {
     const mockRequest = new Request('https://clerk.com/webhooks', {
       method: 'POST',
       body: mockBody,
-      headers: new Headers({}),
+      headers: new Headers({
+        // Missing all required headers
+      }),
     });
 
-    await expect(verifyWebhook(mockRequest)).rejects.toThrow(
-      'Missing required Svix headers: svix-id, svix-timestamp, svix-signature',
-    );
+    await expect(verifyWebhook(mockRequest)).rejects.toThrow('svix-id, svix-timestamp, svix-signature');
   });
 
   it('throws when signing secret is missing', async () => {
@@ -44,24 +50,26 @@ describe('verifyWebhook', () => {
       body: mockBody,
       headers: new Headers({
         'svix-id': 'msg_123',
-        'svix-timestamp': '1614265330',
+        'svix-timestamp': (Date.now() / 1000).toString(),
         'svix-signature': 'v1,test_signature',
       }),
     });
 
-    await expect(verifyWebhook(mockRequest)).rejects.toThrow(
-      'Missing webhook signing secret. Set the CLERK_WEBHOOK_SIGNING_SECRET environment variable with the webhook secret from the Clerk Dashboard.',
-    );
+    await expect(verifyWebhook(mockRequest)).rejects.toThrow('Missing webhook signing secret');
   });
 
   it('validates webhook request requirements', async () => {
+    const svixId = 'msg_123';
+    const svixTimestamp = (Date.now() / 1000).toString();
+    const validSignature = createValidSignature(svixId, svixTimestamp, mockBody);
+
     const mockRequest = new Request('https://clerk.com/webhooks', {
       method: 'POST',
       body: mockBody,
       headers: new Headers({
-        'svix-id': 'msg_123',
-        'svix-timestamp': '1614265330',
-        'svix-signature': 'v1,test_signature',
+        'svix-id': svixId,
+        'svix-timestamp': svixTimestamp,
+        'svix-signature': validSignature,
       }),
     });
 
@@ -72,4 +80,141 @@ describe('verifyWebhook', () => {
     expect(result).toHaveProperty('type', 'user.created');
     expect(result).toHaveProperty('data.id', 'user_123');
   });
+
+  it('should accept valid signatures', async () => {
+    const svixId = 'msg_123';
+    const svixTimestamp = (Date.now() / 1000).toString();
+    const validSignature = createValidSignature(svixId, svixTimestamp, mockBody);
+
+    const mockRequest = new Request('https://clerk.com/webhooks', {
+      method: 'POST',
+      body: mockBody,
+      headers: new Headers({
+        'svix-id': svixId,
+        'svix-timestamp': svixTimestamp,
+        'svix-signature': validSignature,
+      }),
+    });
+
+    // Should accept and return parsed data
+    const result = await verifyWebhook(mockRequest);
+    expect(result).toHaveProperty('type', 'user.created');
+    expect(result).toHaveProperty('data.id', 'user_123');
+  });
+
+  it('should reject invalid signatures', async () => {
+    const svixId = 'msg_123';
+    const svixTimestamp = (Date.now() / 1000).toString();
+    const invalidSignature = 'v1,invalid_signature_here';
+
+    const mockRequest = new Request('https://clerk.com/webhooks', {
+      method: 'POST',
+      body: mockBody,
+      headers: new Headers({
+        'svix-id': svixId,
+        'svix-timestamp': svixTimestamp,
+        'svix-signature': invalidSignature,
+      }),
+    });
+
+    // Should reject invalid signatures
+    await expect(verifyWebhook(mockRequest)).rejects.toThrow('No matching signature found');
+  });
+
+  it('should handle multiple signatures in header', async () => {
+    const svixId = 'msg_123';
+    const svixTimestamp = (Date.now() / 1000).toString();
+    const validSignature = createValidSignature(svixId, svixTimestamp, mockBody);
+    const invalidSignature = 'v1,invalid_signature';
+
+    const mockRequest = new Request('https://clerk.com/webhooks', {
+      method: 'POST',
+      body: mockBody,
+      headers: new Headers({
+        'svix-id': svixId,
+        'svix-timestamp': svixTimestamp,
+        'svix-signature': `${invalidSignature} ${validSignature}`,
+      }),
+    });
+
+    // Should accept if any signature in the list is valid
+    const result = await verifyWebhook(mockRequest);
+    expect(result).toHaveProperty('type', 'user.created');
+    expect(result).toHaveProperty('data.id', 'user_123');
+  });
+
+  it('should handle signatures without version prefixes for backward compatibility', async () => {
+    const svixId = 'msg_123';
+    const svixTimestamp = (Date.now() / 1000).toString();
+    // Test with Standard Webhooks generated signature without custom prefix
+    const validSignature = createValidSignature(svixId, svixTimestamp, mockBody);
+
+    const mockRequest = new Request('https://clerk.com/webhooks', {
+      method: 'POST',
+      body: mockBody,
+      headers: new Headers({
+        'svix-id': svixId,
+        'svix-timestamp': svixTimestamp,
+        'svix-signature': validSignature,
+      }),
+    });
+
+    // Should accept signatures without version prefixes
+    const result = await verifyWebhook(mockRequest);
+    expect(result).toHaveProperty('type', 'user.created');
+    expect(result).toHaveProperty('data.id', 'user_123');
+  });
+
+  it('should verify against Standard Webhooks specification', async () => {
+    // Test with proper Clerk webhook format
+    const clerkPayload = '{"type":"user.created","data":{"id":"user_123","email":"[email protected]"}}';
+    const msgId = 'msg_test123';
+    const timestamp = (Date.now() / 1000).toString();
+
+    const validSignature = createValidSignature(msgId, timestamp, clerkPayload);
+
+    const mockRequest = new Request('https://clerk.com/webhooks', {
+      method: 'POST',
+      body: clerkPayload,
+      headers: new Headers({
+        'svix-id': msgId,
+        'svix-timestamp': timestamp,
+        'svix-signature': validSignature,
+      }),
+    });
+
+    const result = await verifyWebhook(mockRequest, { signingSecret: mockSecret });
+    expect(result).toHaveProperty('type', 'user.created');
+    expect(result).toHaveProperty('data.id', 'user_123');
+  });
+
+  it('should handle whitespace-only header values correctly', async () => {
+    const mockRequest = new Request('https://clerk.com/webhooks', {
+      method: 'POST',
+      body: mockBody,
+      headers: new Headers({
+        'svix-id': '', // Empty - should be caught
+        'svix-timestamp': '   ', // Whitespace - should be caught
+        'svix-signature': 'v1,signature',
+      }),
+    });
+
+    // This should fail because whitespace-only headers should be treated as missing
+    await expect(verifyWebhook(mockRequest)).rejects.toThrow('Missing required webhook headers');
+  });
+
+  it('should handle mixed empty and whitespace headers correctly', async () => {
+    const mockRequest = new Request('https://clerk.com/webhooks', {
+      method: 'POST',
+      body: mockBody,
+      headers: new Headers({
+        'svix-id': '  \t  ', // Mixed whitespace and tabs
+        'svix-timestamp': '\n', // Newline character
+        'svix-signature': '', // Empty string
+      }),
+    });
+
+    // All should be treated as missing
+    await expect(verifyWebhook(mockRequest)).rejects.toThrow('svix-id, svix-timestamp, svix-signature');
+  });
 });

packages/backend/src/webhooks.ts

@@ -1,6 +1,6 @@
 import { getEnvVariable } from '@clerk/shared/getEnvVariable';
-import crypto from 'crypto';
 import { errorThrower } from 'src/util/shared';
+import { Webhook } from 'standardwebhooks';
 
 import type { WebhookEvent } from './api/resources/Webhooks';
 
@@ -14,16 +14,44 @@ export type VerifyWebhookOptions = {
   signingSecret?: string;
 };
 
+// Standard Webhooks header names
+const STANDARD_WEBHOOK_ID_HEADER = 'webhook-id';
+const STANDARD_WEBHOOK_TIMESTAMP_HEADER = 'webhook-timestamp';
+const STANDARD_WEBHOOK_SIGNATURE_HEADER = 'webhook-signature';
+
+// Svix header names (for mapping)
 const SVIX_ID_HEADER = 'svix-id';
 const SVIX_TIMESTAMP_HEADER = 'svix-timestamp';
 const SVIX_SIGNATURE_HEADER = 'svix-signature';
 
-const REQUIRED_SVIX_HEADERS = [SVIX_ID_HEADER, SVIX_TIMESTAMP_HEADER, SVIX_SIGNATURE_HEADER] as const;
-
 export * from './api/resources/Webhooks';
 
 /**
- * Verifies the authenticity of a webhook request using Svix. Returns a promise that resolves to the verified webhook event data.
+ * Maps Svix headers to Standard Webhooks headers for compatibility
+ */
+function createStandardWebhookHeaders(request: Request): Record<string, string> {
+  const headers: Record<string, string> = {};
+
+  // Map Svix headers to Standard Webhooks headers
+  const svixId = request.headers.get(SVIX_ID_HEADER)?.trim();
+  const svixTimestamp = request.headers.get(SVIX_TIMESTAMP_HEADER)?.trim();
+  const svixSignature = request.headers.get(SVIX_SIGNATURE_HEADER)?.trim();
+
+  if (svixId) {
+    headers[STANDARD_WEBHOOK_ID_HEADER] = svixId;
+  }
+  if (svixTimestamp) {
+    headers[STANDARD_WEBHOOK_TIMESTAMP_HEADER] = svixTimestamp;
+  }
+  if (svixSignature) {
+    headers[STANDARD_WEBHOOK_SIGNATURE_HEADER] = svixSignature;
+  }
+
+  return headers;
+}
+
+/**
+ * Verifies the authenticity of a webhook request using Standard Webhooks. Returns a promise that resolves to the verified webhook event data.
  *
  * @param request - The request object.
  * @param options - Optional configuration object.
@@ -56,39 +84,53 @@ export * from './api/resources/Webhooks';
  */
 export async function verifyWebhook(request: Request, options: VerifyWebhookOptions = {}): Promise<WebhookEvent> {
   const secret = options.signingSecret ?? getEnvVariable('CLERK_WEBHOOK_SIGNING_SECRET');
-  const svixId = request.headers.get(SVIX_ID_HEADER);
-  const svixTimestamp = request.headers.get(SVIX_TIMESTAMP_HEADER);
-  const svixSignature = request.headers.get(SVIX_SIGNATURE_HEADER);
 
   if (!secret) {
     return errorThrower.throw(
       'Missing webhook signing secret. Set the CLERK_WEBHOOK_SIGNING_SECRET environment variable with the webhook secret from the Clerk Dashboard.',
     );
   }
 
-  if (!svixId || !svixTimestamp || !svixSignature) {
-    const missingHeaders = REQUIRED_SVIX_HEADERS.filter(header => !request.headers.has(header));
-    return errorThrower.throw(`Missing required Svix headers: ${missingHeaders.join(', ')}`);
+  // Check for required Svix headers
+  const webhookId = request.headers.get(SVIX_ID_HEADER)?.trim();
+  const webhookTimestamp = request.headers.get(SVIX_TIMESTAMP_HEADER)?.trim();
+  const webhookSignature = request.headers.get(SVIX_SIGNATURE_HEADER)?.trim();
+
+  if (!webhookId || !webhookTimestamp || !webhookSignature) {
+    const missingHeaders = [];
+
+    if (!webhookId) {
+      missingHeaders.push(SVIX_ID_HEADER);
+    }
+    if (!webhookTimestamp) {
+      missingHeaders.push(SVIX_TIMESTAMP_HEADER);
+    }
+    if (!webhookSignature) {
+      missingHeaders.push(SVIX_SIGNATURE_HEADER);
+    }
+
+    return errorThrower.throw(`Missing required webhook headers: ${missingHeaders.join(', ')}`);
   }
 
   const body = await request.text();
 
-  const signedContent = `${svixId}.${svixTimestamp}.${body}`;
+  // Create Standard Webhooks compatible headers mapping
+  const standardHeaders = createStandardWebhookHeaders(request);
 
-  const secretBytes = Buffer.from(secret.split('_')[1], 'base64');
+  // Initialize Standard Webhooks verifier
+  const webhook = new Webhook(secret);
 
-  const constructedSignature = crypto.createHmac('sha256', secretBytes).update(signedContent).digest('base64');
+  try {
+    // Verify using Standard Webhooks - this provides constant-time comparison
+    // and proper signature format handling
+    const payload = webhook.verify(body, standardHeaders) as Record<string, unknown>;
 
-  // svixSignature can be a string with one or more space separated signatures
-  if (svixSignature.split(' ').includes(constructedSignature)) {
-    return errorThrower.throw('Incoming webhook does not have a valid signature');
+    return {
+      type: payload.type,
+      object: 'event',
+      data: payload.data,
+    } as WebhookEvent;
+  } catch (e) {
+    return errorThrower.throw(`Unable to verify incoming webhook: ${e instanceof Error ? e.message : 'Unknown error'}`);
   }
-
-  const payload = JSON.parse(body);
-
-  return {
-    type: payload.type,
-    object: 'event',
-    data: payload.data,
-  } as WebhookEvent;
 }