@hookflo/tern 4.3.0 → 4.3.1-beta

package/README.md

@@ -189,6 +189,10 @@ app.post('/webhooks/stripe', createWebhookHandler({
 | **Grafana** | HMAC-SHA256 | ✅ Tested |
 | **Doppler** | HMAC-SHA256 | ✅ Tested |
 | **Sanity** | HMAC-SHA256 | ✅ Tested |
+| **Svix** | HMAC-SHA256 | ⚠️ Untested for now |
+| **Linear** | HMAC-SHA256 | ⚠️ Untested for now |
+| **PagerDuty** | HMAC-SHA256 | ⚠️ Untested for now |
+| **Twilio** | HMAC-SHA1 | ⚠️ Untested for now |
 | **Razorpay** | HMAC-SHA256 | 🔄 Pending |
 | **Vercel** | HMAC-SHA256 | 🔄 Pending |
 

package/dist/index.js

@@ -189,6 +189,10 @@ class WebhookVerificationService {
             case 'workos':
             case 'sentry':
             case 'vercel':
+            case 'linear':
+            case 'pagerduty':
+            case 'twilio':
+            case 'svix':
                 return this.pickString(payload?.id) || null;
             case 'doppler':
                 return this.pickString(payload?.event?.id, metadata?.id) || null;
@@ -220,7 +224,13 @@ class WebhookVerificationService {
         if (headers.has('x-hub-signature-256'))
             return 'github';
         if (headers.has('svix-signature'))
-            return 'clerk';
+            return headers.has('svix-id') ? 'svix' : 'clerk';
+        if (headers.has('linear-signature'))
+            return 'linear';
+        if (headers.has('x-pagerduty-signature'))
+            return 'pagerduty';
+        if (headers.has('x-twilio-signature'))
+            return 'twilio';
         if (headers.has('workos-signature'))
             return 'workos';
         if (headers.has('webhook-signature')) {

package/dist/platforms/algorithms.js

@@ -51,6 +51,27 @@ exports.platformAlgorithmConfigs = {
         },
         description: "Clerk webhooks use HMAC-SHA256 with base64 encoding",
     },
+    svix: {
+        platform: 'svix',
+        signatureConfig: {
+            algorithm: 'hmac-sha256',
+            headerName: 'svix-signature',
+            headerFormat: 'raw',
+            timestampHeader: 'svix-timestamp',
+            timestampFormat: 'unix',
+            payloadFormat: 'custom',
+            customConfig: {
+                signatureFormat: 'v1={signature}',
+                payloadFormat: '{id}.{timestamp}.{body}',
+                encoding: 'base64',
+                secretEncoding: 'base64',
+                idHeader: 'svix-id',
+                idHeaderAliases: ['webhook-id'],
+                timestampHeaderAliases: ['webhook-timestamp'],
+            },
+        },
+        description: 'Svix webhooks use HMAC-SHA256 with Standard Webhooks format',
+    },
     dodopayments: {
         platform: "dodopayments",
         signatureConfig: {
@@ -287,6 +308,50 @@ exports.platformAlgorithmConfigs = {
         },
         description: "Sanity webhooks use Stripe-compatible HMAC-SHA256 with base64 encoded signature and plain UTF-8 secret",
     },
+    linear: {
+        platform: 'linear',
+        signatureConfig: {
+            algorithm: 'hmac-sha256',
+            headerName: 'linear-signature',
+            headerFormat: 'raw',
+            payloadFormat: 'raw',
+            customConfig: {
+                replayToleranceMs: 60000,
+            },
+        },
+        description: 'Linear webhooks use HMAC-SHA256 on the raw body with a 60s timestamp replay window',
+    },
+    pagerduty: {
+        platform: 'pagerduty',
+        signatureConfig: {
+            algorithm: 'hmac-sha256',
+            headerName: 'x-pagerduty-signature',
+            headerFormat: 'raw',
+            payloadFormat: 'raw',
+            prefix: 'v1=',
+            customConfig: {
+                signatureFormat: 'v1={signature}',
+                comparePrefixed: true,
+            },
+        },
+        description: 'PagerDuty webhooks use HMAC-SHA256 with v1=<hex> signatures',
+    },
+    twilio: {
+        platform: 'twilio',
+        signatureConfig: {
+            algorithm: 'hmac-sha1',
+            headerName: 'x-twilio-signature',
+            headerFormat: 'raw',
+            payloadFormat: 'custom',
+            customConfig: {
+                payloadFormat: '{url}',
+                encoding: 'base64',
+                secretEncoding: 'utf8',
+                validateBodySHA256: true,
+            },
+        },
+        description: 'Twilio webhooks use HMAC-SHA1 with base64 signatures (URL canonicalization required)',
+    },
     custom: {
         platform: "custom",
         signatureConfig: {

package/dist/types.d.ts

@@ -1,8 +1,9 @@
-export type WebhookPlatform = 'custom' | 'clerk' | 'github' | 'stripe' | 'shopify' | 'vercel' | 'polar' | 'dodopayments' | 'gitlab' | 'paddle' | 'razorpay' | 'lemonsqueezy' | 'workos' | 'woocommerce' | 'replicateai' | 'falai' | 'sentry' | 'grafana' | 'doppler' | 'sanity' | 'unknown';
+export type WebhookPlatform = 'custom' | 'clerk' | 'svix' | 'github' | 'stripe' | 'shopify' | 'vercel' | 'polar' | 'dodopayments' | 'gitlab' | 'paddle' | 'razorpay' | 'lemonsqueezy' | 'workos' | 'woocommerce' | 'replicateai' | 'falai' | 'sentry' | 'grafana' | 'doppler' | 'sanity' | 'linear' | 'pagerduty' | 'twilio' | 'unknown';
 export declare enum WebhookPlatformKeys {
     GitHub = "github",
     Stripe = "stripe",
     Clerk = "clerk",
+    Svix = "svix",
     DodoPayments = "dodopayments",
     Shopify = "shopify",
     Vercel = "vercel",
@@ -19,6 +20,9 @@ export declare enum WebhookPlatformKeys {
     Grafana = "grafana",
     Doppler = "doppler",
     Sanity = "sanity",
+    Linear = "linear",
+    PagerDuty = "pagerduty",
+    Twilio = "twilio",
     Custom = "custom",
     Unknown = "unknown"
 }

package/dist/types.js

@@ -6,6 +6,7 @@ var WebhookPlatformKeys;
     WebhookPlatformKeys["GitHub"] = "github";
     WebhookPlatformKeys["Stripe"] = "stripe";
     WebhookPlatformKeys["Clerk"] = "clerk";
+    WebhookPlatformKeys["Svix"] = "svix";
     WebhookPlatformKeys["DodoPayments"] = "dodopayments";
     WebhookPlatformKeys["Shopify"] = "shopify";
     WebhookPlatformKeys["Vercel"] = "vercel";
@@ -22,6 +23,9 @@ var WebhookPlatformKeys;
     WebhookPlatformKeys["Grafana"] = "grafana";
     WebhookPlatformKeys["Doppler"] = "doppler";
     WebhookPlatformKeys["Sanity"] = "sanity";
+    WebhookPlatformKeys["Linear"] = "linear";
+    WebhookPlatformKeys["PagerDuty"] = "pagerduty";
+    WebhookPlatformKeys["Twilio"] = "twilio";
     WebhookPlatformKeys["Custom"] = "custom";
     WebhookPlatformKeys["Unknown"] = "unknown";
 })(WebhookPlatformKeys || (exports.WebhookPlatformKeys = WebhookPlatformKeys = {}));

package/dist/verifiers/algorithms.d.ts

@@ -18,6 +18,8 @@ export declare abstract class AlgorithmBasedVerifier extends WebhookVerifier {
     protected extractMetadata(request: Request): Record<string, any>;
 }
 export declare class GenericHMACVerifier extends AlgorithmBasedVerifier {
+    private validateLinearReplayWindow;
+    private validateTwilioBodyHash;
     private resolveSentryPayloadCandidates;
     verify(request: Request): Promise<WebhookVerificationResult>;
 }

package/dist/verifiers/algorithms.js

@@ -63,9 +63,34 @@ class AlgorithmBasedVerifier extends base_1.WebhookVerifier {
                         }
                         // Accept "v1=<signature>" variants used by some providers/docs.
                         if (sig.startsWith("v1=")) {
-                            const [, value] = sig.split("=", 2);
-                            if (value) {
-                                normalized.push(value.trim());
+                            if (this.config.customConfig?.comparePrefixed) {
+                                for (const fragment of sig.split(',')) {
+                                    const candidate = fragment.trim();
+                                    if (candidate.startsWith('v1=')) {
+                                        normalized.push(candidate);
+                                    }
+                                }
+                            }
+                            else {
+                                const [, value] = sig.split("=", 2);
+                                if (value) {
+                                    normalized.push(value.trim());
+                                }
+                            }
+                            continue;
+                        }
+                        for (const fragment of sig.split(',')) {
+                            const candidate = fragment.trim();
+                            if (candidate.startsWith('v1=')) {
+                                if (this.config.customConfig?.comparePrefixed) {
+                                    normalized.push(candidate);
+                                }
+                                else {
+                                    const [, value] = candidate.split('=', 2);
+                                    if (value) {
+                                        normalized.push(value.trim());
+                                    }
+                                }
                             }
                         }
                     }
@@ -77,7 +102,9 @@ class AlgorithmBasedVerifier extends base_1.WebhookVerifier {
     extractTimestamp(request) {
         if (!this.config.timestampHeader)
             return null;
-        const timestampHeader = request.headers.get(this.config.timestampHeader);
+        const timestampHeader = request.headers.get(this.config.timestampHeader)
+            || this.config.customConfig?.timestampHeaderAliases?.map((alias) => request.headers.get(alias)).find(Boolean)
+            || null;
         if (!timestampHeader)
             return null;
         switch (this.config.timestampFormat) {
@@ -108,7 +135,7 @@ class AlgorithmBasedVerifier extends base_1.WebhookVerifier {
             return true;
         // These platforms have timestampHeader in config but timestamp
         // is optional in their spec — validate only if present, never mandate
-        const optionalTimestampPlatforms = ['vercel', 'sentry', 'grafana'];
+        const optionalTimestampPlatforms = ['vercel', 'sentry', 'grafana', 'twilio'];
         if (optionalTimestampPlatforms.includes(this.platform))
             return false;
         // For all other platforms: infer from config
@@ -152,7 +179,7 @@ class AlgorithmBasedVerifier extends base_1.WebhookVerifier {
         }
         const customFormat = this.config.customConfig.payloadFormat;
         if (customFormat.includes("{id}") && customFormat.includes("{timestamp}")) {
-            const id = request.headers.get(this.config.customConfig.idHeader || "x-webhook-id");
+            const id = request.headers.get(this.config.customConfig.idHeader || "x-webhook-id") || this.config.customConfig?.idHeaderAliases?.map((alias) => request.headers.get(alias)).find(Boolean);
             const timestamp = request.headers.get(this.config.timestampHeader ||
                 this.config.customConfig?.timestampHeader ||
                 "x-webhook-timestamp");
@@ -167,6 +194,11 @@ class AlgorithmBasedVerifier extends base_1.WebhookVerifier {
                 .replace("{timestamp}", timestamp.trim() || "")
                 .replace("{body}", rawBody);
         }
+        if (customFormat.includes('{url}')) {
+            return customFormat
+                .replace('{url}', request.url)
+                .replace('{body}', rawBody);
+        }
         if (customFormat.includes("{timestamp}") &&
             customFormat.includes("{body}")) {
             const timestamp = this.extractTimestampFromSignature(request) ||
@@ -250,6 +282,40 @@ class AlgorithmBasedVerifier extends base_1.WebhookVerifier {
 }
 exports.AlgorithmBasedVerifier = AlgorithmBasedVerifier;
 class GenericHMACVerifier extends AlgorithmBasedVerifier {
+    validateLinearReplayWindow(rawBody) {
+        if (this.platform !== 'linear')
+            return null;
+        try {
+            const parsed = JSON.parse(rawBody);
+            const rawTimestamp = parsed.webhookTimestamp;
+            const timestampMs = Number(rawTimestamp);
+            if (!Number.isFinite(timestampMs)) {
+                return 'Missing or invalid Linear webhookTimestamp';
+            }
+            const replayToleranceMs = this.config.customConfig?.replayToleranceMs || 60000;
+            if (Math.abs(Date.now() - timestampMs) > replayToleranceMs) {
+                return 'Linear webhook timestamp is outside the replay window';
+            }
+        }
+        catch {
+            return 'Linear webhook replay check requires JSON payload';
+        }
+        return null;
+    }
+    validateTwilioBodyHash(rawBody, request) {
+        if (this.platform !== 'twilio' || !this.config.customConfig?.validateBodySHA256) {
+            return null;
+        }
+        const url = new URL(request.url);
+        const bodySha = url.searchParams.get('bodySHA256');
+        if (!bodySha)
+            return null;
+        const computed = (0, crypto_1.createHash)('sha256').update(rawBody).digest('hex');
+        if (!this.safeCompare(computed, bodySha)) {
+            return 'Twilio bodySHA256 query param does not match payload hash';
+        }
+        return null;
+    }
     resolveSentryPayloadCandidates(rawBody, request) {
         const candidates = [
             this.formatPayload(rawBody, request),
@@ -289,6 +355,24 @@ class GenericHMACVerifier extends AlgorithmBasedVerifier {
                 };
             }
             const rawBody = await request.text();
+            const linearReplayError = this.validateLinearReplayWindow(rawBody);
+            if (linearReplayError) {
+                return {
+                    isValid: false,
+                    error: linearReplayError,
+                    errorCode: 'TIMESTAMP_EXPIRED',
+                    platform: this.platform,
+                };
+            }
+            const twilioBodyHashError = this.validateTwilioBodyHash(rawBody, request);
+            if (twilioBodyHashError) {
+                return {
+                    isValid: false,
+                    error: twilioBodyHashError,
+                    errorCode: 'INVALID_SIGNATURE',
+                    platform: this.platform,
+                };
+            }
             let timestamp = null;
             if (this.config.headerFormat === "comma-separated") {
                 timestamp = this.extractTimestampFromSignature(request);
@@ -322,7 +406,7 @@ class GenericHMACVerifier extends AlgorithmBasedVerifier {
                     if (this.config.customConfig?.encoding === "base64") {
                         isValid = this.verifyHMACWithBase64(payload, signature, algorithm);
                     }
-                    else if (this.config.headerFormat === "prefixed") {
+                    else if (this.config.headerFormat === "prefixed" || this.config.customConfig?.comparePrefixed) {
                         isValid = this.verifyHMACWithPrefix(payload, signature, algorithm);
                     }
                     else {

package/package.json

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