@hookflo/tern 2.0.3-experimental.0 → 2.2.3

package/README.md

@@ -210,7 +210,15 @@ const result = await WebhookVerificationService.verify(request, stripeConfig);
 
 ### Other Platforms
 - **Dodo Payments**: HMAC-SHA256
-- **Shopify**: HMAC-SHA256
+- **Paddle**: HMAC-SHA256
+- **Razorpay**: HMAC-SHA256
+- **Lemon Squeezy**: HMAC-SHA256
+- **Auth0**: HMAC-SHA256
+- **WorkOS**: HMAC-SHA256 (`workos-signature`, `t/v1`)
+- **WooCommerce**: HMAC-SHA256 (base64 signature)
+- **ReplicateAI**: HMAC-SHA256 (Standard Webhooks style)
+- **fal.ai**: ED25519 (`x-fal-webhook-signature`)
+- **Shopify**: HMAC-SHA256 (base64 signature)
 - **Vercel**: HMAC-SHA256
 - **Polar**: HMAC-SHA256
 - **Supabase**: Token-based authentication
@@ -369,6 +377,58 @@ export default {
 };
 ```
 
+
+### Are new platforms available in framework middlewares automatically?
+
+Yes. All built-in platforms are available in:
+- `createWebhookMiddleware` (`@hookflo/tern/express`)
+- `createWebhookHandler` (`@hookflo/tern/nextjs`)
+- `createWebhookHandler` (`@hookflo/tern/cloudflare`)
+
+You only change `platform` and `secret` per route.
+
+### Platform route examples (Express / Next.js / Cloudflare)
+
+```typescript
+// Express (Razorpay)
+app.post('/webhooks/razorpay', createWebhookMiddleware({
+  platform: 'razorpay',
+  secret: process.env.RAZORPAY_WEBHOOK_SECRET!,
+}), (req, res) => res.json({ ok: true }));
+
+// Next.js (WorkOS)
+export const POST = createWebhookHandler({
+  platform: 'workos',
+  secret: process.env.WORKOS_WEBHOOK_SECRET!,
+  handler: async (payload) => ({ received: true, type: payload.type }),
+});
+
+// Cloudflare (Lemon Squeezy)
+const handleLemonSqueezy = createWebhookHandler({
+  platform: 'lemonsqueezy',
+  secretEnv: 'LEMON_SQUEEZY_WEBHOOK_SECRET',
+  handler: async () => ({ received: true }),
+});
+```
+
+### fal.ai production usage
+
+fal.ai uses **ED25519** (`x-fal-webhook-signature`) and signs:
+`{request-id}.{user-id}.{timestamp}.{sha256(body)}`.
+
+Use one of these strategies:
+1. **Public key as `secret`** (recommended for framework adapters).
+2. **JWKS auto-resolution** via the built-in fal.ai config (`x-fal-webhook-key-id` + fal JWKS URL).
+
+```typescript
+// Next.js with explicit public key PEM as secret
+export const POST = createWebhookHandler({
+  platform: 'falai',
+  secret: process.env.FAL_PUBLIC_KEY_PEM!,
+  handler: async (payload, metadata) => ({ received: true, requestId: metadata.requestId }),
+});
+```
+
 ## API Reference
 
 ### WebhookVerificationService
@@ -545,4 +605,3 @@ export const POST = createWebhookHandler({
   handler: async (payload) => ({ received: true, event: payload.event ?? payload.type }),
 });
 ```
-

package/dist/adapters/cloudflare.js

@@ -12,7 +12,7 @@ function createWebhookHandler(options) {
             }
             const result = await index_1.WebhookVerificationService.verifyWithPlatformConfig(request, options.platform, secret, options.toleranceInSeconds, options.normalize);
             if (!result.isValid) {
-                return Response.json({ error: result.error, platform: result.platform }, { status: 400 });
+                return Response.json({ error: result.error, errorCode: result.errorCode, platform: result.platform, metadata: result.metadata }, { status: 400 });
             }
             const data = await options.handler(result.payload, env, result.metadata || {});
             return Response.json(data);

package/dist/adapters/express.js

@@ -9,7 +9,7 @@ function createWebhookMiddleware(options) {
             const webRequest = await (0, shared_1.toWebRequest)(req);
             const result = await index_1.WebhookVerificationService.verifyWithPlatformConfig(webRequest, options.platform, options.secret, options.toleranceInSeconds, options.normalize);
             if (!result.isValid) {
-                res.status(400).json({ error: result.error, platform: result.platform });
+                res.status(400).json({ error: result.error, errorCode: result.errorCode, platform: result.platform, metadata: result.metadata });
                 return;
             }
             req.webhook = result;

package/dist/adapters/nextjs.js

@@ -7,7 +7,7 @@ function createWebhookHandler(options) {
         try {
             const result = await index_1.WebhookVerificationService.verifyWithPlatformConfig(request, options.platform, options.secret, options.toleranceInSeconds, options.normalize);
             if (!result.isValid) {
-                return Response.json({ error: result.error, platform: result.platform }, { status: 400 });
+                return Response.json({ error: result.error, errorCode: result.errorCode, platform: result.platform, metadata: result.metadata }, { status: 400 });
             }
             const data = await options.handler(result.payload, result.metadata || {});
             return Response.json(data);

package/dist/index.js

@@ -79,6 +79,7 @@ class WebhookVerificationService {
         if (detectedPlatform !== 'unknown' && secrets[detectedPlatform]) {
             return this.verifyWithPlatformConfig(requestClone, detectedPlatform, secrets[detectedPlatform], toleranceInSeconds, normalize);
         }
+        const failedAttempts = [];
         for (const [platform, secret] of Object.entries(secrets)) {
             if (!secret) {
                 continue;
@@ -87,12 +88,25 @@ class WebhookVerificationService {
             if (result.isValid) {
                 return result;
             }
+            failedAttempts.push({
+                platform: platform.toLowerCase(),
+                error: result.error,
+                errorCode: result.errorCode,
+            });
         }
+        const details = failedAttempts
+            .map((attempt) => `${attempt.platform}: ${attempt.error || 'verification failed'}`)
+            .join('; ');
         return {
             isValid: false,
-            error: 'Unable to verify webhook with provided platform secrets',
-            errorCode: 'VERIFICATION_ERROR',
+            error: details
+                ? `Unable to verify webhook with provided platform secrets. Attempts -> ${details}`
+                : 'Unable to verify webhook with provided platform secrets',
+            errorCode: failedAttempts.find((attempt) => attempt.errorCode)?.errorCode || 'VERIFICATION_ERROR',
             platform: detectedPlatform,
+            metadata: {
+                attempts: failedAttempts,
+            },
         };
     }
     static detectPlatform(request) {
@@ -103,12 +117,32 @@ class WebhookVerificationService {
             return 'github';
         if (headers.has('svix-signature'))
             return 'clerk';
-        if (headers.has('webhook-signature'))
+        if (headers.has('workos-signature'))
+            return 'workos';
+        if (headers.has('webhook-signature')) {
+            const userAgent = headers.get('user-agent')?.toLowerCase() || '';
+            if (userAgent.includes('polar'))
+                return 'polar';
+            if (userAgent.includes('replicate'))
+                return 'replicateai';
             return 'dodopayments';
+        }
         if (headers.has('x-gitlab-token'))
             return 'gitlab';
         if (headers.has('x-polar-signature'))
             return 'polar';
+        if (headers.has('paddle-signature'))
+            return 'paddle';
+        if (headers.has('x-razorpay-signature'))
+            return 'razorpay';
+        if (headers.has('x-signature'))
+            return 'lemonsqueezy';
+        if (headers.has('x-auth0-signature'))
+            return 'auth0';
+        if (headers.has('x-wc-webhook-signature'))
+            return 'woocommerce';
+        if (headers.has('x-fal-signature') || headers.has('x-fal-webhook-signature'))
+            return 'falai';
         if (headers.has('x-shopify-hmac-sha256'))
             return 'shopify';
         if (headers.has('x-vercel-signature'))

package/dist/platforms/algorithms.js

@@ -45,6 +45,7 @@ exports.platformAlgorithmConfigs = {
                 signatureFormat: 'v1={signature}',
                 payloadFormat: '{id}.{timestamp}.{body}',
                 encoding: 'base64',
+                secretEncoding: 'base64',
                 idHeader: 'svix-id',
             },
         },
@@ -63,6 +64,7 @@ exports.platformAlgorithmConfigs = {
                 signatureFormat: 'v1={signature}',
                 payloadFormat: '{id}.{timestamp}.{body}',
                 encoding: 'base64',
+                secretEncoding: 'base64',
                 idHeader: 'webhook-id',
             },
         },
@@ -74,10 +76,13 @@ exports.platformAlgorithmConfigs = {
             algorithm: 'hmac-sha256',
             headerName: 'x-shopify-hmac-sha256',
             headerFormat: 'raw',
-            timestampHeader: 'x-shopify-shop-domain',
             payloadFormat: 'raw',
+            customConfig: {
+                encoding: 'base64',
+                secretEncoding: 'utf8',
+            },
         },
-        description: 'Shopify webhooks use HMAC-SHA256',
+        description: 'Shopify webhooks use HMAC-SHA256 with base64 encoded signature',
     },
     vercel: {
         platform: 'vercel',
@@ -95,13 +100,20 @@ exports.platformAlgorithmConfigs = {
         platform: 'polar',
         signatureConfig: {
             algorithm: 'hmac-sha256',
-            headerName: 'x-polar-signature',
+            headerName: 'webhook-signature',
             headerFormat: 'raw',
-            timestampHeader: 'x-polar-timestamp',
+            timestampHeader: 'webhook-timestamp',
             timestampFormat: 'unix',
-            payloadFormat: 'raw',
+            payloadFormat: 'custom',
+            customConfig: {
+                signatureFormat: 'v1={signature}',
+                payloadFormat: '{id}.{timestamp}.{body}',
+                encoding: 'base64',
+                secretEncoding: 'base64',
+                idHeader: 'webhook-id',
+            },
         },
-        description: 'Polar webhooks use HMAC-SHA256',
+        description: 'Polar webhooks use HMAC-SHA256 with Standard Webhooks format',
     },
     supabase: {
         platform: 'supabase',
@@ -131,6 +143,116 @@ exports.platformAlgorithmConfigs = {
         },
         description: 'GitLab webhooks use HMAC-SHA256 with X-Gitlab-Token header',
     },
+    paddle: {
+        platform: 'paddle',
+        signatureConfig: {
+            algorithm: 'hmac-sha256',
+            headerName: 'paddle-signature',
+            headerFormat: 'comma-separated',
+            payloadFormat: 'custom',
+            customConfig: {
+                timestampKey: 'ts',
+                signatureKey: 'h1',
+                payloadFormat: '{timestamp}:{body}',
+            },
+        },
+        description: 'Paddle webhooks use HMAC-SHA256 with Paddle-Signature (ts/h1) header format',
+    },
+    razorpay: {
+        platform: 'razorpay',
+        signatureConfig: {
+            algorithm: 'hmac-sha256',
+            headerName: 'x-razorpay-signature',
+            headerFormat: 'raw',
+            payloadFormat: 'raw',
+        },
+        description: 'Razorpay webhooks use HMAC-SHA256 with X-Razorpay-Signature header',
+    },
+    lemonsqueezy: {
+        platform: 'lemonsqueezy',
+        signatureConfig: {
+            algorithm: 'hmac-sha256',
+            headerName: 'x-signature',
+            headerFormat: 'raw',
+            payloadFormat: 'raw',
+        },
+        description: 'Lemon Squeezy webhooks use HMAC-SHA256 with X-Signature header',
+    },
+    auth0: {
+        platform: 'auth0',
+        signatureConfig: {
+            algorithm: 'hmac-sha256',
+            headerName: 'x-auth0-signature',
+            headerFormat: 'raw',
+            payloadFormat: 'raw',
+        },
+        description: 'Auth0 webhooks use HMAC-SHA256 with X-Auth0-Signature header',
+    },
+    workos: {
+        platform: 'workos',
+        signatureConfig: {
+            algorithm: 'hmac-sha256',
+            headerName: 'workos-signature',
+            headerFormat: 'comma-separated',
+            payloadFormat: 'custom',
+            customConfig: {
+                timestampKey: 't',
+                signatureKey: 'v1',
+                payloadFormat: '{timestamp}.{body}',
+            },
+        },
+        description: 'WorkOS webhooks use HMAC-SHA256 with WorkOS-Signature (t/v1) format',
+    },
+    woocommerce: {
+        platform: 'woocommerce',
+        signatureConfig: {
+            algorithm: 'hmac-sha256',
+            headerName: 'x-wc-webhook-signature',
+            headerFormat: 'raw',
+            payloadFormat: 'raw',
+            customConfig: {
+                encoding: 'base64',
+                secretEncoding: 'utf8',
+            },
+        },
+        description: 'WooCommerce webhooks use HMAC-SHA256 with base64 encoded signature',
+    },
+    replicateai: {
+        platform: 'replicateai',
+        signatureConfig: {
+            algorithm: 'hmac-sha256',
+            headerName: 'webhook-signature',
+            headerFormat: 'raw',
+            timestampHeader: 'webhook-timestamp',
+            timestampFormat: 'unix',
+            payloadFormat: 'custom',
+            customConfig: {
+                signatureFormat: 'v1={signature}',
+                payloadFormat: '{id}.{timestamp}.{body}',
+                encoding: 'base64',
+                secretEncoding: 'base64',
+                idHeader: 'webhook-id',
+            },
+        },
+        description: 'Replicate webhooks use HMAC-SHA256 with Standard Webhooks (svix-style) format',
+    },
+    falai: {
+        platform: 'falai',
+        signatureConfig: {
+            algorithm: 'ed25519',
+            headerName: 'x-fal-webhook-signature',
+            headerFormat: 'raw',
+            payloadFormat: 'custom',
+            customConfig: {
+                requestIdHeader: 'x-fal-request-id',
+                userIdHeader: 'x-fal-user-id',
+                timestampHeader: 'x-fal-webhook-timestamp',
+                kidHeader: 'x-fal-webhook-key-id',
+                jwksUrl: 'https://rest.alpha.fal.ai/.well-known/jwks.json',
+            },
+        },
+        description: 'fal.ai webhooks use ED25519 with a signed request/user/timestamp/body-hash payload',
+    },
     custom: {
         platform: 'custom',
         signatureConfig: {
@@ -178,8 +300,9 @@ function validateSignatureConfig(config) {
         case 'hmac-sha512':
             return true;
         case 'rsa-sha256':
-        case 'ed25519':
             return !!config.customConfig?.publicKey;
+        case 'ed25519':
+            return !!config.customConfig?.publicKey || !!config.customConfig?.jwksUrl;
         case 'custom':
             return !!config.customConfig;
         default:

package/dist/test.js

@@ -35,6 +35,40 @@ function createClerkSignature(body, secret, id, timestamp) {
     hmac.update(signedContent);
     return `v1,${hmac.digest('base64')}`;
 }
+function createStandardWebhooksSignature(body, secret, id, timestamp) {
+    const signedContent = `${id}.${timestamp}.${body}`;
+    const base64Secret = secret.includes('_') ? secret.split('_')[1] : secret;
+    const secretBytes = new Uint8Array(Buffer.from(base64Secret, 'base64'));
+    const hmac = (0, crypto_1.createHmac)('sha256', secretBytes);
+    hmac.update(signedContent);
+    return `v1,${hmac.digest('base64')}`;
+}
+function createPaddleSignature(body, secret, timestamp) {
+    const signedPayload = `${timestamp}:${body}`;
+    const hmac = (0, crypto_1.createHmac)('sha256', secret);
+    hmac.update(signedPayload);
+    return `ts=${timestamp};h1=${hmac.digest('hex')}`;
+}
+function createShopifySignature(body, secret) {
+    const hmac = (0, crypto_1.createHmac)('sha256', secret);
+    hmac.update(body);
+    return hmac.digest('base64');
+}
+function createWooCommerceSignature(body, secret) {
+    const hmac = (0, crypto_1.createHmac)('sha256', secret);
+    hmac.update(body);
+    return hmac.digest('base64');
+}
+function createWorkOSSignature(body, secret, timestamp) {
+    const signedPayload = `${timestamp}.${body}`;
+    const hmac = (0, crypto_1.createHmac)('sha256', secret);
+    hmac.update(signedPayload);
+    return `t=${timestamp},v1=${hmac.digest('hex')}`;
+}
+function createFalPayloadToSign(body, requestId, userId, timestamp) {
+    const bodyHash = (0, crypto_1.createHash)('sha256').update(body).digest('hex');
+    return `${requestId}.${userId}.${timestamp}.${bodyHash}`;
+}
 async function runTests() {
     console.log('🧪 Running Webhook Verification Tests...\n');
     // Test 1: Stripe Webhook
@@ -248,6 +282,24 @@ async function runTests() {
     catch (error) {
         console.log('   ❌ verifyAny test failed:', error);
     }
+    // Test 10.5: verifyAny error diagnostics
+    console.log('\n10.5. Testing verifyAny error diagnostics...');
+    try {
+        const unknownRequest = createMockRequest({
+            'content-type': 'application/json',
+        });
+        const invalidVerifyAny = await index_1.WebhookVerificationService.verifyAny(unknownRequest, {
+            stripe: testSecret,
+            shopify: testSecret,
+        });
+        const hasDetailedErrors = Boolean(invalidVerifyAny.error
+            && invalidVerifyAny.error.includes('Attempts ->')
+            && invalidVerifyAny.metadata?.attempts?.length === 2);
+        console.log('   ✅ verifyAny diagnostics:', hasDetailedErrors ? 'PASSED' : 'FAILED');
+    }
+    catch (error) {
+        console.log('   ❌ verifyAny diagnostics test failed:', error);
+    }
     // Test 11: Normalization for Stripe
     console.log('\n11. Testing payload normalization...');
     try {
@@ -289,6 +341,195 @@ async function runTests() {
     catch (error) {
         console.log('   ❌ Category registry test failed:', error);
     }
+    // Test 13: Razorpay
+    console.log('\n13. Testing Razorpay webhook...');
+    try {
+        const hmac = (0, crypto_1.createHmac)('sha256', testSecret);
+        hmac.update(testBody);
+        const signature = hmac.digest('hex');
+        const request = createMockRequest({
+            'x-razorpay-signature': signature,
+            'content-type': 'application/json',
+        });
+        const result = await index_1.WebhookVerificationService.verifyWithPlatformConfig(request, 'razorpay', testSecret);
+        console.log('   ✅ Razorpay:', result.isValid ? 'PASSED' : 'FAILED');
+    }
+    catch (error) {
+        console.log('   ❌ Razorpay test failed:', error);
+    }
+    // Test 14: Lemon Squeezy
+    console.log('\n14. Testing Lemon Squeezy webhook...');
+    try {
+        const hmac = (0, crypto_1.createHmac)('sha256', testSecret);
+        hmac.update(testBody);
+        const signature = hmac.digest('hex');
+        const request = createMockRequest({
+            'x-signature': signature,
+            'content-type': 'application/json',
+        });
+        const result = await index_1.WebhookVerificationService.verifyWithPlatformConfig(request, 'lemonsqueezy', testSecret);
+        console.log('   ✅ Lemon Squeezy:', result.isValid ? 'PASSED' : 'FAILED');
+    }
+    catch (error) {
+        console.log('   ❌ Lemon Squeezy test failed:', error);
+    }
+    // Test 15: Paddle
+    console.log('\n15. Testing Paddle webhook...');
+    try {
+        const timestamp = Math.floor(Date.now() / 1000);
+        const signature = createPaddleSignature(testBody, testSecret, timestamp);
+        const request = createMockRequest({
+            'paddle-signature': signature,
+            'content-type': 'application/json',
+        });
+        const result = await index_1.WebhookVerificationService.verifyWithPlatformConfig(request, 'paddle', testSecret);
+        console.log('   ✅ Paddle:', result.isValid ? 'PASSED' : 'FAILED');
+    }
+    catch (error) {
+        console.log('   ❌ Paddle test failed:', error);
+    }
+    // Test 16: Auth0
+    console.log('\n16. Testing Auth0 webhook...');
+    try {
+        const hmac = (0, crypto_1.createHmac)('sha256', testSecret);
+        hmac.update(testBody);
+        const signature = hmac.digest('hex');
+        const request = createMockRequest({
+            'x-auth0-signature': signature,
+            'content-type': 'application/json',
+        });
+        const result = await index_1.WebhookVerificationService.verifyWithPlatformConfig(request, 'auth0', testSecret);
+        console.log('   ✅ Auth0:', result.isValid ? 'PASSED' : 'FAILED');
+    }
+    catch (error) {
+        console.log('   ❌ Auth0 test failed:', error);
+    }
+    // Test 17: WorkOS
+    console.log('\n17. Testing WorkOS webhook...');
+    try {
+        const timestamp = Math.floor(Date.now() / 1000);
+        const signature = createWorkOSSignature(testBody, testSecret, timestamp);
+        const request = createMockRequest({
+            'workos-signature': signature,
+            'content-type': 'application/json',
+        });
+        const result = await index_1.WebhookVerificationService.verifyWithPlatformConfig(request, 'workos', testSecret);
+        console.log('   ✅ WorkOS:', result.isValid ? 'PASSED' : 'FAILED');
+    }
+    catch (error) {
+        console.log('   ❌ WorkOS test failed:', error);
+    }
+    // Test 17.5: Shopify
+    console.log('\n17.5. Testing Shopify webhook...');
+    try {
+        const signature = createShopifySignature(testBody, testSecret);
+        const request = createMockRequest({
+            'x-shopify-hmac-sha256': signature,
+            'content-type': 'application/json',
+        });
+        const result = await index_1.WebhookVerificationService.verifyWithPlatformConfig(request, 'shopify', testSecret);
+        console.log('   ✅ Shopify:', result.isValid ? 'PASSED' : 'FAILED');
+        if (!result.isValid) {
+            console.log('   ❌ Error:', result.error);
+        }
+    }
+    catch (error) {
+        console.log('   ❌ Shopify test failed:', error);
+    }
+    // Test 18: WooCommerce
+    console.log('\n18. Testing WooCommerce webhook...');
+    try {
+        const signature = createWooCommerceSignature(testBody, testSecret);
+        const request = createMockRequest({
+            'x-wc-webhook-signature': signature,
+            'content-type': 'application/json',
+        });
+        const result = await index_1.WebhookVerificationService.verifyWithPlatformConfig(request, 'woocommerce', testSecret);
+        console.log('   ✅ WooCommerce:', result.isValid ? 'PASSED' : 'FAILED');
+    }
+    catch (error) {
+        console.log('   ❌ WooCommerce test failed:', error);
+    }
+    // Test 18.5: Polar (Standard Webhooks)
+    console.log('\n18.5. Testing Polar webhook...');
+    try {
+        const secret = `whsec_${Buffer.from(testSecret).toString('base64')}`;
+        const webhookId = 'polar-webhook-id-1';
+        const timestamp = Math.floor(Date.now() / 1000);
+        const signature = createStandardWebhooksSignature(testBody, secret, webhookId, timestamp);
+        const request = createMockRequest({
+            'webhook-signature': signature,
+            'webhook-id': webhookId,
+            'webhook-timestamp': timestamp.toString(),
+            'user-agent': 'Polar.sh Webhooks',
+            'content-type': 'application/json',
+        });
+        const result = await index_1.WebhookVerificationService.verifyWithPlatformConfig(request, 'polar', secret);
+        const detectedPlatform = index_1.WebhookVerificationService.detectPlatform(request);
+        console.log('   ✅ Polar verification:', result.isValid ? 'PASSED' : 'FAILED');
+        console.log('   ✅ Polar auto-detect:', detectedPlatform === 'polar' ? 'PASSED' : 'FAILED');
+    }
+    catch (error) {
+        console.log('   ❌ Polar test failed:', error);
+    }
+    // Test 19: Replicate
+    console.log('\n19. Testing Replicate webhook...');
+    try {
+        const secret = `whsec_${Buffer.from(testSecret).toString('base64')}`;
+        const webhookId = 'replicate-webhook-id-1';
+        const timestamp = Math.floor(Date.now() / 1000);
+        const signature = createStandardWebhooksSignature(testBody, secret, webhookId, timestamp);
+        const request = createMockRequest({
+            'webhook-signature': signature,
+            'webhook-id': webhookId,
+            'webhook-timestamp': timestamp.toString(),
+            'user-agent': 'Replicate-Webhooks/1.0',
+            'content-type': 'application/json',
+        });
+        const result = await index_1.WebhookVerificationService.verifyWithPlatformConfig(request, 'replicateai', secret);
+        console.log('   ✅ Replicate:', result.isValid ? 'PASSED' : 'FAILED');
+    }
+    catch (error) {
+        console.log('   ❌ Replicate test failed:', error);
+    }
+    // Test 20: fal.ai
+    console.log('\n20. Testing fal.ai webhook...');
+    try {
+        const { privateKey, publicKey } = (0, crypto_1.generateKeyPairSync)('ed25519');
+        const requestId = 'fal-request-id';
+        const userId = 'fal-user-id';
+        const timestamp = Math.floor(Date.now() / 1000).toString();
+        const payloadToSign = createFalPayloadToSign(testBody, requestId, userId, timestamp);
+        const payloadBytes = new Uint8Array(Buffer.from(payloadToSign));
+        const signature = (0, crypto_1.sign)(null, payloadBytes, privateKey).toString('base64');
+        const request = createMockRequest({
+            'x-fal-webhook-signature': signature,
+            'x-fal-request-id': requestId,
+            'x-fal-user-id': userId,
+            'x-fal-webhook-timestamp': timestamp,
+            'content-type': 'application/json',
+        });
+        const result = await index_1.WebhookVerificationService.verify(request, {
+            platform: 'falai',
+            secret: '',
+            signatureConfig: {
+                algorithm: 'ed25519',
+                headerName: 'x-fal-webhook-signature',
+                headerFormat: 'raw',
+                payloadFormat: 'custom',
+                customConfig: {
+                    publicKey: publicKey.export({ type: 'spki', format: 'pem' }).toString(),
+                    requestIdHeader: 'x-fal-request-id',
+                    userIdHeader: 'x-fal-user-id',
+                    timestampHeader: 'x-fal-webhook-timestamp',
+                },
+            },
+        });
+        console.log('   ✅ fal.ai:', result.isValid ? 'PASSED' : 'FAILED');
+    }
+    catch (error) {
+        console.log('   ❌ fal.ai test failed:', error);
+    }
     console.log('\n🎉 All tests completed!');
 }
 // Run tests if this file is executed directly

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-export type WebhookPlatform = 'custom' | 'clerk' | 'supabase' | 'github' | 'stripe' | 'shopify' | 'vercel' | 'polar' | 'dodopayments' | 'gitlab' | 'unknown';
+export type WebhookPlatform = 'custom' | 'clerk' | 'supabase' | 'github' | 'stripe' | 'shopify' | 'vercel' | 'polar' | 'dodopayments' | 'gitlab' | 'paddle' | 'razorpay' | 'lemonsqueezy' | 'auth0' | 'workos' | 'woocommerce' | 'replicateai' | 'falai' | 'unknown';
 export declare enum WebhookPlatformKeys {
     GitHub = "github",
     Stripe = "stripe",
@@ -9,6 +9,14 @@ export declare enum WebhookPlatformKeys {
     Polar = "polar",
     Supabase = "supabase",
     GitLab = "gitlab",
+    Paddle = "paddle",
+    Razorpay = "razorpay",
+    LemonSqueezy = "lemonsqueezy",
+    Auth0 = "auth0",
+    WorkOS = "workos",
+    WooCommerce = "woocommerce",
+    ReplicateAI = "replicateai",
+    FalAI = "falai",
     Custom = "custom",
     Unknown = "unknown"
 }

package/dist/types.js

@@ -12,6 +12,14 @@ var WebhookPlatformKeys;
     WebhookPlatformKeys["Polar"] = "polar";
     WebhookPlatformKeys["Supabase"] = "supabase";
     WebhookPlatformKeys["GitLab"] = "gitlab";
+    WebhookPlatformKeys["Paddle"] = "paddle";
+    WebhookPlatformKeys["Razorpay"] = "razorpay";
+    WebhookPlatformKeys["LemonSqueezy"] = "lemonsqueezy";
+    WebhookPlatformKeys["Auth0"] = "auth0";
+    WebhookPlatformKeys["WorkOS"] = "workos";
+    WebhookPlatformKeys["WooCommerce"] = "woocommerce";
+    WebhookPlatformKeys["ReplicateAI"] = "replicateai";
+    WebhookPlatformKeys["FalAI"] = "falai";
     WebhookPlatformKeys["Custom"] = "custom";
     WebhookPlatformKeys["Unknown"] = "unknown";
 })(WebhookPlatformKeys || (exports.WebhookPlatformKeys = WebhookPlatformKeys = {}));

package/dist/utils.js

@@ -112,9 +112,34 @@ function detectPlatformFromHeaders(headers) {
         return 'clerk';
     }
     // Dodo Payments
+    if (headerMap.has('workos-signature')) {
+        return 'workos';
+    }
     if (headerMap.has('webhook-signature')) {
+        const userAgent = headerMap.get('user-agent') || '';
+        if (userAgent.includes('replicate')) {
+            return 'replicateai';
+        }
         return 'dodopayments';
     }
+    if (headerMap.has('paddle-signature')) {
+        return 'paddle';
+    }
+    if (headerMap.has('x-razorpay-signature')) {
+        return 'razorpay';
+    }
+    if (headerMap.has('x-signature')) {
+        return 'lemonsqueezy';
+    }
+    if (headerMap.has('x-auth0-signature')) {
+        return 'auth0';
+    }
+    if (headerMap.has('x-wc-webhook-signature')) {
+        return 'woocommerce';
+    }
+    if (headerMap.has('x-fal-signature') || headerMap.has('x-fal-webhook-signature')) {
+        return 'falai';
+    }
     // Shopify
     if (headerMap.has('x-shopify-hmac-sha256')) {
         return 'shopify';
@@ -127,6 +152,12 @@ function detectPlatformFromHeaders(headers) {
     if (headerMap.has('x-polar-signature')) {
         return 'polar';
     }
+    if (headerMap.has('webhook-signature')) {
+        const userAgent = (headerMap.get('user-agent') || '').toLowerCase();
+        if (userAgent.includes('polar')) {
+            return 'polar';
+        }
+    }
     // Supabase
     if (headerMap.has('x-webhook-token')) {
         return 'supabase';

package/dist/verifiers/algorithms.d.ts

@@ -5,6 +5,7 @@ export declare abstract class AlgorithmBasedVerifier extends WebhookVerifier {
     protected platform: WebhookPlatform;
     constructor(secret: string, config: SignatureConfig, platform: WebhookPlatform, toleranceInSeconds?: number);
     abstract verify(request: Request): Promise<WebhookVerificationResult>;
+    protected parseDelimitedHeader(headerValue: string): Record<string, string>;
     protected extractSignature(request: Request): string | null;
     protected extractTimestamp(request: Request): number | null;
     protected extractTimestampFromSignature(request: Request): number | null;
@@ -18,6 +19,11 @@ export declare abstract class AlgorithmBasedVerifier extends WebhookVerifier {
 export declare class GenericHMACVerifier extends AlgorithmBasedVerifier {
     verify(request: Request): Promise<WebhookVerificationResult>;
 }
+export declare class Ed25519Verifier extends AlgorithmBasedVerifier {
+    private resolvePublicKey;
+    private buildFalPayload;
+    verify(request: Request): Promise<WebhookVerificationResult>;
+}
 export declare class HMACSHA256Verifier extends GenericHMACVerifier {
     constructor(secret: string, config: SignatureConfig, platform?: WebhookPlatform, toleranceInSeconds?: number);
 }

package/dist/verifiers/algorithms.js

@@ -1,37 +1,49 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.HMACSHA512Verifier = exports.HMACSHA1Verifier = exports.HMACSHA256Verifier = exports.GenericHMACVerifier = exports.AlgorithmBasedVerifier = void 0;
+exports.HMACSHA512Verifier = exports.HMACSHA1Verifier = exports.HMACSHA256Verifier = exports.Ed25519Verifier = exports.GenericHMACVerifier = exports.AlgorithmBasedVerifier = void 0;
 exports.createAlgorithmVerifier = createAlgorithmVerifier;
 const crypto_1 = require("crypto");
 const base_1 = require("./base");
+const ed25519KeyCache = new Map();
 class AlgorithmBasedVerifier extends base_1.WebhookVerifier {
     constructor(secret, config, platform, toleranceInSeconds = 300) {
         super(secret, toleranceInSeconds);
         this.config = config;
         this.platform = platform;
     }
+    parseDelimitedHeader(headerValue) {
+        const parts = headerValue.split(/[;,]/);
+        const values = {};
+        for (const part of parts) {
+            const trimmed = part.trim();
+            if (!trimmed)
+                continue;
+            const equalIndex = trimmed.indexOf('=');
+            if (equalIndex === -1)
+                continue;
+            const key = trimmed.slice(0, equalIndex).trim();
+            const value = trimmed.slice(equalIndex + 1).trim();
+            if (key && value) {
+                values[key] = value;
+            }
+        }
+        return values;
+    }
     extractSignature(request) {
         const headerValue = request.headers.get(this.config.headerName);
         if (!headerValue)
             return null;
         switch (this.config.headerFormat) {
             case 'prefixed':
-                // For GitHub, return the full signature including prefix for comparison
                 return headerValue;
-            case 'comma-separated':
-                // Handle comma-separated format like Stripe: "t=1234567890,v1=abc123"
-                const parts = headerValue.split(',');
-                const sigMap = {};
-                for (const part of parts) {
-                    const [key, value] = part.split('=');
-                    if (key && value) {
-                        sigMap[key] = value;
-                    }
-                }
-                return sigMap.v1 || sigMap.signature || null;
+            case 'comma-separated': {
+                const sigMap = this.parseDelimitedHeader(headerValue);
+                const signatureKey = this.config.customConfig?.signatureKey || 'v1';
+                return sigMap[signatureKey] || sigMap.signature || sigMap.v1 || null;
+            }
             case 'raw':
             default:
-                if (this.platform === 'clerk' || this.platform === 'dodopayments') {
+                if (this.config.customConfig?.signatureFormat?.includes('v1=')) {
                     const signatures = headerValue.split(' ');
                     for (const sig of signatures) {
                         const [version, signature] = sig.split(',');
@@ -56,37 +68,29 @@ class AlgorithmBasedVerifier extends base_1.WebhookVerifier {
             case 'iso':
                 return Math.floor(new Date(timestampHeader).getTime() / 1000);
             case 'custom':
-                // Custom timestamp parsing logic can be added here
                 return parseInt(timestampHeader, 10);
             default:
                 return parseInt(timestampHeader, 10);
         }
     }
     extractTimestampFromSignature(request) {
-        // For platforms like Stripe where timestamp is embedded in signature
-        if (this.config.headerFormat === 'comma-separated') {
-            const headerValue = request.headers.get(this.config.headerName);
-            if (!headerValue)
-                return null;
-            const parts = headerValue.split(',');
-            const sigMap = {};
-            for (const part of parts) {
-                const [key, value] = part.split('=');
-                if (key && value) {
-                    sigMap[key] = value;
-                }
-            }
-            return sigMap.t ? parseInt(sigMap.t, 10) : null;
+        if (this.config.headerFormat !== 'comma-separated') {
+            return null;
         }
-        return null;
+        const headerValue = request.headers.get(this.config.headerName);
+        if (!headerValue)
+            return null;
+        const sigMap = this.parseDelimitedHeader(headerValue);
+        const timestampKey = this.config.customConfig?.timestampKey || 't';
+        return sigMap[timestampKey] ? parseInt(sigMap[timestampKey], 10) : null;
     }
     formatPayload(rawBody, request) {
         switch (this.config.payloadFormat) {
-            case 'timestamped':
-                // For Stripe, timestamp is embedded in signature
+            case 'timestamped': {
                 const timestamp = this.extractTimestampFromSignature(request)
                     || this.extractTimestamp(request);
                 return timestamp ? `${timestamp}.${rawBody}` : rawBody;
+            }
             case 'custom':
                 return this.formatCustomPayload(rawBody, request);
             case 'raw':
@@ -99,7 +103,6 @@ class AlgorithmBasedVerifier extends base_1.WebhookVerifier {
             return rawBody;
         }
         const customFormat = this.config.customConfig.payloadFormat;
-        // Handle Clerk-style format: {id}.{timestamp}.{body}
         if (customFormat.includes('{id}') && customFormat.includes('{timestamp}')) {
             const id = request.headers.get(this.config.customConfig.idHeader || 'x-webhook-id');
             const timestamp = request.headers.get(this.config.timestampHeader || 'x-webhook-timestamp');
@@ -108,10 +111,10 @@ class AlgorithmBasedVerifier extends base_1.WebhookVerifier {
                 .replace('{timestamp}', timestamp || '')
                 .replace('{body}', rawBody);
         }
-        // Handle Stripe-style format: {timestamp}.{body}
         if (customFormat.includes('{timestamp}')
             && customFormat.includes('{body}')) {
-            const timestamp = this.extractTimestamp(request);
+            const timestamp = this.extractTimestampFromSignature(request)
+                || this.extractTimestamp(request);
             return customFormat
                 .replace('{timestamp}', timestamp?.toString() || '')
                 .replace('{body}', rawBody);
@@ -131,9 +134,15 @@ class AlgorithmBasedVerifier extends base_1.WebhookVerifier {
         return this.safeCompare(signature, expectedSignature);
     }
     verifyHMACWithBase64(payload, signature, algorithm = 'sha256') {
-        // For platforms like Clerk that use base64 encoding
-        const secretBytes = new Uint8Array(Buffer.from(this.secret.split('_')[1], 'base64'));
-        const hmac = (0, crypto_1.createHmac)(algorithm, secretBytes);
+        const secretEncoding = this.config.customConfig?.secretEncoding || 'base64';
+        let secretMaterial = this.secret;
+        if (secretEncoding === 'base64') {
+            const base64Secret = this.secret.includes('_')
+                ? this.secret.split('_').slice(1).join('_')
+                : this.secret;
+            secretMaterial = new Uint8Array(Buffer.from(base64Secret, 'base64'));
+        }
+        const hmac = (0, crypto_1.createHmac)(algorithm, secretMaterial);
         hmac.update(payload);
         const expectedSignature = hmac.digest('base64');
         return this.safeCompare(signature, expectedSignature);
@@ -142,41 +151,38 @@ class AlgorithmBasedVerifier extends base_1.WebhookVerifier {
         const metadata = {
             algorithm: this.config.algorithm,
         };
-        // Add timestamp if available
-        const timestamp = this.extractTimestamp(request);
+        const timestamp = this.extractTimestamp(request) || this.extractTimestampFromSignature(request);
         if (timestamp) {
             metadata.timestamp = timestamp.toString();
         }
-        // Add platform-specific metadata
         switch (this.platform) {
             case 'github':
                 metadata.event = request.headers.get('x-github-event');
                 metadata.delivery = request.headers.get('x-github-delivery');
                 break;
-            case 'stripe':
-                // Extract Stripe-specific metadata from signature
+            case 'stripe': {
                 const headerValue = request.headers.get(this.config.headerName);
                 if (headerValue && this.config.headerFormat === 'comma-separated') {
-                    const parts = headerValue.split(',');
-                    const sigMap = {};
-                    for (const part of parts) {
-                        const [key, value] = part.split('=');
-                        if (key && value) {
-                            sigMap[key] = value;
-                        }
-                    }
+                    const sigMap = this.parseDelimitedHeader(headerValue);
                     metadata.id = sigMap.id;
                 }
                 break;
+            }
             case 'clerk':
-                metadata.id = request.headers.get('svix-id');
+            case 'dodopayments':
+            case 'replicateai':
+                metadata.id = request.headers.get(this.config.customConfig?.idHeader || 'webhook-id');
+                break;
+            case 'workos':
+                metadata.id = request.headers.get(this.config.customConfig?.idHeader || 'webhook-id');
+                break;
+            default:
                 break;
         }
         return metadata;
     }
 }
 exports.AlgorithmBasedVerifier = AlgorithmBasedVerifier;
-// Generic HMAC Verifier that handles all HMAC-based algorithms
 class GenericHMACVerifier extends AlgorithmBasedVerifier {
     async verify(request) {
         try {
@@ -190,17 +196,13 @@ class GenericHMACVerifier extends AlgorithmBasedVerifier {
                 };
             }
             const rawBody = await request.text();
-            // Extract timestamp based on platform configuration
             let timestamp = null;
             if (this.config.headerFormat === 'comma-separated') {
-                // For platforms like Stripe where timestamp is embedded in signature
                 timestamp = this.extractTimestampFromSignature(request);
             }
             else {
-                // For platforms with separate timestamp header
                 timestamp = this.extractTimestamp(request);
             }
-            // Validate timestamp if required
             if (timestamp && !this.isTimestampValid(timestamp)) {
                 return {
                     isValid: false,
@@ -209,21 +211,16 @@ class GenericHMACVerifier extends AlgorithmBasedVerifier {
                     platform: this.platform,
                 };
             }
-            // Format payload according to platform requirements
             const payload = this.formatPayload(rawBody, request);
-            // Verify signature based on platform configuration
             let isValid = false;
             const algorithm = this.config.algorithm.replace('hmac-', '');
             if (this.config.customConfig?.encoding === 'base64') {
-                // For platforms like Clerk that use base64 encoding
                 isValid = this.verifyHMACWithBase64(payload, signature, algorithm);
             }
             else if (this.config.headerFormat === 'prefixed') {
-                // For platforms like GitHub that use prefixed signatures
                 isValid = this.verifyHMACWithPrefix(payload, signature, algorithm);
             }
             else {
-                // Standard HMAC verification
                 isValid = this.verifyHMAC(payload, signature, algorithm);
             }
             if (!isValid) {
@@ -234,7 +231,6 @@ class GenericHMACVerifier extends AlgorithmBasedVerifier {
                     platform: this.platform,
                 };
             }
-            // Parse payload
             let parsedPayload;
             try {
                 parsedPayload = JSON.parse(rawBody);
@@ -242,7 +238,6 @@ class GenericHMACVerifier extends AlgorithmBasedVerifier {
             catch (e) {
                 parsedPayload = rawBody;
             }
-            // Extract platform-specific metadata
             const metadata = this.extractMetadata(request);
             return {
                 isValid: true,
@@ -262,7 +257,115 @@ class GenericHMACVerifier extends AlgorithmBasedVerifier {
     }
 }
 exports.GenericHMACVerifier = GenericHMACVerifier;
-// Legacy verifiers for backward compatibility
+class Ed25519Verifier extends AlgorithmBasedVerifier {
+    async resolvePublicKey(request) {
+        const configPublicKey = this.config.customConfig?.publicKey;
+        if (configPublicKey) {
+            return configPublicKey;
+        }
+        if (this.secret && this.secret.trim().length > 0) {
+            return this.secret;
+        }
+        const jwksUrl = this.config.customConfig?.jwksUrl;
+        const kidHeader = this.config.customConfig?.kidHeader;
+        const kid = kidHeader ? request.headers.get(kidHeader) : null;
+        if (!jwksUrl || !kid) {
+            return null;
+        }
+        const cacheKey = `${jwksUrl}:${kid}`;
+        if (ed25519KeyCache.has(cacheKey)) {
+            return ed25519KeyCache.get(cacheKey);
+        }
+        const response = await fetch(jwksUrl);
+        if (!response.ok) {
+            return null;
+        }
+        const body = await response.json();
+        const key = body.keys?.find((entry) => entry.kid === kid);
+        if (!key) {
+            return null;
+        }
+        const keyObject = (0, crypto_1.createPublicKey)({ key, format: 'jwk' });
+        const pem = keyObject.export({ type: 'spki', format: 'pem' }).toString();
+        ed25519KeyCache.set(cacheKey, pem);
+        return pem;
+    }
+    buildFalPayload(rawBody, request) {
+        const requestIdHeader = this.config.customConfig?.requestIdHeader || 'x-fal-request-id';
+        const userIdHeader = this.config.customConfig?.userIdHeader || 'x-fal-user-id';
+        const timestampHeader = this.config.customConfig?.timestampHeader || 'x-fal-webhook-timestamp';
+        const requestId = request.headers.get(requestIdHeader) || '';
+        const userId = request.headers.get(userIdHeader) || '';
+        const timestamp = request.headers.get(timestampHeader) || '';
+        const bodyHash = (0, crypto_1.createHash)('sha256').update(rawBody).digest('hex');
+        return `${requestId}.${userId}.${timestamp}.${bodyHash}`;
+    }
+    async verify(request) {
+        try {
+            const signature = this.extractSignature(request);
+            if (!signature) {
+                return {
+                    isValid: false,
+                    error: `Missing signature header: ${this.config.headerName}`,
+                    errorCode: 'MISSING_SIGNATURE',
+                    platform: this.platform,
+                };
+            }
+            const rawBody = await request.text();
+            const payload = this.platform === 'falai'
+                ? this.buildFalPayload(rawBody, request)
+                : this.formatPayload(rawBody, request);
+            const publicKey = await this.resolvePublicKey(request);
+            if (!publicKey) {
+                return {
+                    isValid: false,
+                    error: 'Missing public key for ED25519 verification',
+                    errorCode: 'VERIFICATION_ERROR',
+                    platform: this.platform,
+                };
+            }
+            const signatureBytes = new Uint8Array(Buffer.from(signature, 'base64'));
+            const keyObject = (0, crypto_1.createPublicKey)(publicKey);
+            const payloadBytes = new Uint8Array(Buffer.from(payload));
+            const isValid = (0, crypto_1.verify)(null, payloadBytes, keyObject, signatureBytes);
+            if (!isValid) {
+                return {
+                    isValid: false,
+                    error: 'Invalid signature',
+                    errorCode: 'INVALID_SIGNATURE',
+                    platform: this.platform,
+                };
+            }
+            let parsedPayload;
+            try {
+                parsedPayload = JSON.parse(rawBody);
+            }
+            catch (e) {
+                parsedPayload = rawBody;
+            }
+            return {
+                isValid: true,
+                platform: this.platform,
+                payload: parsedPayload,
+                metadata: {
+                    algorithm: this.config.algorithm,
+                    requestId: request.headers.get(this.config.customConfig?.requestIdHeader || 'x-fal-request-id'),
+                    userId: request.headers.get(this.config.customConfig?.userIdHeader || 'x-fal-user-id'),
+                    timestamp: request.headers.get(this.config.customConfig?.timestampHeader || 'x-fal-webhook-timestamp') || undefined,
+                },
+            };
+        }
+        catch (error) {
+            return {
+                isValid: false,
+                error: `${this.platform} verification error: ${error.message}`,
+                errorCode: 'VERIFICATION_ERROR',
+                platform: this.platform,
+            };
+        }
+    }
+}
+exports.Ed25519Verifier = Ed25519Verifier;
 class HMACSHA256Verifier extends GenericHMACVerifier {
     constructor(secret, config, platform = 'unknown', toleranceInSeconds = 300) {
         super(secret, config, platform, toleranceInSeconds);
@@ -281,17 +384,16 @@ class HMACSHA512Verifier extends GenericHMACVerifier {
     }
 }
 exports.HMACSHA512Verifier = HMACSHA512Verifier;
-// Factory function to create verifiers based on algorithm
 function createAlgorithmVerifier(secret, config, platform = 'unknown', toleranceInSeconds = 300) {
     switch (config.algorithm) {
         case 'hmac-sha256':
         case 'hmac-sha1':
         case 'hmac-sha512':
             return new GenericHMACVerifier(secret, config, platform, toleranceInSeconds);
-        case 'rsa-sha256':
         case 'ed25519':
+            return new Ed25519Verifier(secret, config, platform, toleranceInSeconds);
+        case 'rsa-sha256':
         case 'custom':
-            // These can be implemented as needed
             throw new Error(`Algorithm ${config.algorithm} not yet implemented`);
         default:
             throw new Error(`Unknown algorithm: ${config.algorithm}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hookflo/tern",
-  "version": "2.0.3-experimental.0",
+  "version": "2.2.3",
   "description": "A robust, scalable webhook verification framework supporting multiple platforms and signature algorithms",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",