@hookflo/tern 4.2.5-beta → 4.2.9-beta

package/README.md

@@ -512,7 +512,40 @@ await controls.alert({
 - `controls.alert()` with no params sends a normal (non-DLQ) alert with internal defaults.
 - `controls.alert({ dlq: true, dlqId })` sends a DLQ alert and attempts replay internally via `controls.replay(dlqId)`.
 - `eventId` is auto-filled from `dlqId` for DLQ alerts.
-- Optional overrides like `message`, `metadata`, `source`, or `branding` can still be passed.
+- Optional overrides like `title`, `message`, `metadata`, `source`, or `branding` are used directly in Slack/Discord payloads.
+
+### Adapter-level alerts (works with and without queue)
+
+If you are not using Upstash controls, you can enable alerting directly in adapters by providing `alerts`.
+This works in **both queue and non-queue** modes.
+
+```ts
+import { createWebhookHandler } from '@hookflo/tern/nextjs';
+
+export const POST = createWebhookHandler({
+  platform: 'stripe',
+  secret: process.env.STRIPE_WEBHOOK_SECRET!,
+  alerts: {
+    slack: { webhookUrl: process.env.SLACK_WEBHOOK_URL! },
+    discord: { webhookUrl: process.env.DISCORD_WEBHOOK_URL! },
+  },
+  alert: {
+    title: 'Alert Recieved',
+    message: 'Alert received in handler',
+  },
+  handler: async (payload, metadata) => {
+    return { ok: true };
+  },
+});
+```
+
+- In non-queue mode, alerts include `source` (platform) and canonical `eventId` from verification.
+- In queue mode, normal alerts are sent on successful enqueue (DLQ alerting remains Upstash-controls based).
+- Adapter-level alert calls do **not** auto-inject metadata; pass explicit alert fields via `alert` for predictable payloads.
+
+### Core SDK queue + alerts
+
+`WebhookVerificationService.handleWithQueue(...)` also supports alerting through the same `alerts` + `alert` options, so core SDK users get the same behavior as framework adapters.
 
 ## Testing
 

package/dist/adapters/cloudflare.d.ts

@@ -1,5 +1,6 @@
 import { WebhookPlatform, NormalizeOptions } from '../types';
 import { QueueOption } from '../upstash/types';
+import type { AlertConfig, SendAlertOptions } from '../notifications/types';
 export interface CloudflareWebhookHandlerOptions<TEnv = Record<string, unknown>, TPayload = any, TMetadata extends Record<string, unknown> = Record<string, unknown>, TResponse = unknown> {
     platform: WebhookPlatform;
     secret?: string;
@@ -7,6 +8,8 @@ export interface CloudflareWebhookHandlerOptions<TEnv = Record<string, unknown>,
     toleranceInSeconds?: number;
     normalize?: boolean | NormalizeOptions;
     queue?: QueueOption;
+    alerts?: AlertConfig;
+    alert?: Omit<SendAlertOptions, 'dlq' | 'dlqId' | 'source' | 'eventId'>;
     onError?: (error: Error) => void;
     handler: (payload: TPayload, env: TEnv, metadata: TMetadata) => Promise<TResponse> | TResponse;
 }

package/dist/adapters/cloudflare.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createWebhookHandler = createWebhookHandler;
 const index_1 = require("../index");
 const queue_1 = require("../upstash/queue");
+const dispatch_1 = require("../notifications/dispatch");
 function createWebhookHandler(options) {
     return async (request, env) => {
         try {
@@ -13,18 +14,41 @@ function createWebhookHandler(options) {
             }
             if (options.queue) {
                 const queueConfig = (0, queue_1.resolveQueueConfig)(options.queue);
-                return (0, queue_1.handleQueuedRequest)(request, {
+                const response = await (0, queue_1.handleQueuedRequest)(request, {
                     platform: options.platform,
                     secret,
                     queueConfig,
                     handler: (payload, metadata) => options.handler(payload, env, metadata),
                     toleranceInSeconds: options.toleranceInSeconds ?? 300,
                 });
+                if (response.ok) {
+                    let eventId;
+                    try {
+                        const body = await response.clone().json();
+                        eventId = typeof body.eventId === 'string' ? body.eventId : undefined;
+                    }
+                    catch {
+                        eventId = undefined;
+                    }
+                    await (0, dispatch_1.dispatchWebhookAlert)({
+                        alerts: options.alerts,
+                        source: options.platform,
+                        eventId,
+                        alert: options.alert,
+                    });
+                }
+                return response;
             }
             const result = await index_1.WebhookVerificationService.verifyWithPlatformConfig(request, options.platform, secret, options.toleranceInSeconds, options.normalize);
             if (!result.isValid) {
                 return Response.json({ error: result.error, errorCode: result.errorCode, platform: result.platform, metadata: result.metadata }, { status: 400 });
             }
+            await (0, dispatch_1.dispatchWebhookAlert)({
+                alerts: options.alerts,
+                source: options.platform,
+                eventId: result.eventId,
+                alert: options.alert,
+            });
             const data = await options.handler(result.payload, env, (result.metadata || {}));
             return Response.json(data);
         }

package/dist/adapters/express.d.ts

@@ -1,6 +1,7 @@
 import { WebhookPlatform, WebhookVerificationResult, NormalizeOptions } from '../types';
 import { QueueOption } from '../upstash/types';
 import { MinimalNodeRequest } from './shared';
+import type { AlertConfig, SendAlertOptions } from '../notifications/types';
 export interface ExpressLikeResponse {
     status: (code: number) => ExpressLikeResponse;
     json: (payload: unknown) => unknown;
@@ -15,6 +16,8 @@ export interface ExpressWebhookMiddlewareOptions {
     toleranceInSeconds?: number;
     normalize?: boolean | NormalizeOptions;
     queue?: QueueOption;
+    alerts?: AlertConfig;
+    alert?: Omit<SendAlertOptions, 'dlq' | 'dlqId' | 'source' | 'eventId'>;
     onError?: (error: Error) => void;
     strictRawBody?: boolean;
 }

package/dist/adapters/express.js

@@ -4,6 +4,7 @@ exports.createWebhookMiddleware = createWebhookMiddleware;
 const index_1 = require("../index");
 const queue_1 = require("../upstash/queue");
 const shared_1 = require("./shared");
+const dispatch_1 = require("../notifications/dispatch");
 function createWebhookMiddleware(options) {
     return async (req, res, next) => {
         try {
@@ -36,6 +37,15 @@ function createWebhookMiddleware(options) {
                     }
                 }
                 res.status(queueResponse.status).json(body ?? {});
+                if (queueResponse.ok) {
+                    const queueResult = body && typeof body === 'object' ? body : undefined;
+                    await (0, dispatch_1.dispatchWebhookAlert)({
+                        alerts: options.alerts,
+                        source: options.platform,
+                        eventId: typeof queueResult?.eventId === 'string' ? queueResult.eventId : undefined,
+                        alert: options.alert,
+                    });
+                }
                 return;
             }
             const result = await index_1.WebhookVerificationService.verifyWithPlatformConfig(webRequest, options.platform, options.secret, options.toleranceInSeconds, options.normalize);
@@ -49,6 +59,12 @@ function createWebhookMiddleware(options) {
                 return;
             }
             req.webhook = result;
+            await (0, dispatch_1.dispatchWebhookAlert)({
+                alerts: options.alerts,
+                source: options.platform,
+                eventId: result.eventId,
+                alert: options.alert,
+            });
             next();
         }
         catch (error) {

package/dist/adapters/nextjs.d.ts

@@ -1,11 +1,14 @@
 import { WebhookPlatform, NormalizeOptions } from '../types';
 import { QueueOption } from '../upstash/types';
+import type { AlertConfig, SendAlertOptions } from '../notifications/types';
 export interface NextWebhookHandlerOptions<TPayload = any, TMetadata extends Record<string, unknown> = Record<string, unknown>, TResponse = unknown> {
     platform: WebhookPlatform;
     secret: string;
     toleranceInSeconds?: number;
     normalize?: boolean | NormalizeOptions;
     queue?: QueueOption;
+    alerts?: AlertConfig;
+    alert?: Omit<SendAlertOptions, 'dlq' | 'dlqId' | 'source' | 'eventId'>;
     onError?: (error: Error) => void;
     handler: (payload: TPayload, metadata: TMetadata) => Promise<TResponse> | TResponse;
 }

package/dist/adapters/nextjs.js

@@ -3,23 +3,47 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createWebhookHandler = createWebhookHandler;
 const index_1 = require("../index");
 const queue_1 = require("../upstash/queue");
+const dispatch_1 = require("../notifications/dispatch");
 function createWebhookHandler(options) {
     return async (request) => {
         try {
             if (options.queue) {
                 const queueConfig = (0, queue_1.resolveQueueConfig)(options.queue);
-                return (0, queue_1.handleQueuedRequest)(request, {
+                const response = await (0, queue_1.handleQueuedRequest)(request, {
                     platform: options.platform,
                     secret: options.secret,
                     queueConfig,
                     handler: options.handler,
                     toleranceInSeconds: options.toleranceInSeconds ?? 300,
                 });
+                if (response.ok) {
+                    let eventId;
+                    try {
+                        const body = await response.clone().json();
+                        eventId = typeof body.eventId === 'string' ? body.eventId : undefined;
+                    }
+                    catch {
+                        eventId = undefined;
+                    }
+                    await (0, dispatch_1.dispatchWebhookAlert)({
+                        alerts: options.alerts,
+                        source: options.platform,
+                        eventId,
+                        alert: options.alert,
+                    });
+                }
+                return response;
             }
             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, errorCode: result.errorCode, platform: result.platform, metadata: result.metadata }, { status: 400 });
             }
+            await (0, dispatch_1.dispatchWebhookAlert)({
+                alerts: options.alerts,
+                source: options.platform,
+                eventId: result.eventId,
+                alert: options.alert,
+            });
             const data = await options.handler(result.payload, (result.metadata || {}));
             return Response.json(data);
         }

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { WebhookConfig, WebhookVerificationResult, WebhookPlatform, SignatureConfig, MultiPlatformSecrets, NormalizeOptions } from './types';
 import type { QueueOption } from './upstash/types';
+import type { AlertConfig, SendAlertOptions } from './notifications/types';
 export declare class WebhookVerificationService {
     static verify<TPayload = unknown>(request: Request, config: WebhookConfig): Promise<WebhookVerificationResult<TPayload>>;
     private static getVerifier;
@@ -20,6 +21,8 @@ export declare class WebhookVerificationService {
         platform: WebhookPlatform;
         secret: string;
         queue: QueueOption;
+        alerts?: AlertConfig;
+        alert?: Omit<SendAlertOptions, 'dlq' | 'dlqId' | 'source' | 'eventId'>;
         handler: (payload: unknown, metadata: Record<string, unknown>) => Promise<unknown> | unknown;
         toleranceInSeconds?: number;
     }): Promise<Response>;

package/dist/index.js

@@ -42,6 +42,7 @@ const algorithms_1 = require("./verifiers/algorithms");
 const custom_algorithms_1 = require("./verifiers/custom-algorithms");
 const algorithms_2 = require("./platforms/algorithms");
 const simple_1 = require("./normalization/simple");
+const dispatch_1 = require("./notifications/dispatch");
 class WebhookVerificationService {
     static async verify(request, config) {
         const verifier = this.getVerifier(config);
@@ -324,13 +325,30 @@ class WebhookVerificationService {
     static async handleWithQueue(request, options) {
         const { resolveQueueConfig, handleQueuedRequest } = await Promise.resolve().then(() => __importStar(require('./upstash/queue')));
         const queueConfig = resolveQueueConfig(options.queue);
-        return handleQueuedRequest(request, {
+        const response = await handleQueuedRequest(request, {
             platform: options.platform,
             secret: options.secret,
             queueConfig,
             handler: options.handler,
             toleranceInSeconds: options.toleranceInSeconds ?? 300,
         });
+        if (response.ok) {
+            let eventId;
+            try {
+                const body = await response.clone().json();
+                eventId = typeof body.eventId === 'string' ? body.eventId : undefined;
+            }
+            catch {
+                eventId = undefined;
+            }
+            await (0, dispatch_1.dispatchWebhookAlert)({
+                alerts: options.alerts,
+                source: options.platform,
+                eventId,
+                alert: options.alert,
+            });
+        }
+        return response;
     }
     static async verifyTokenBased(request, webhookId, webhookToken) {
         return this.verifyTokenAuth(request, webhookId, webhookToken);

package/dist/notifications/channels/discord/build-payload.js

@@ -5,10 +5,12 @@ const utils_1 = require("../../utils");
 const constants_1 = require("../../constants");
 function buildDiscordPayload(input) {
     const isDLQ = input.dlq;
-    const title = isDLQ ? "Dead Letter Queue — Event Failed" : "Webhook Received";
-    const description = isDLQ
+    const fallbackTitle = isDLQ ? "Dead Letter Queue — Event Failed" : "Webhook Received";
+    const title = input.title?.trim() ? input.title : fallbackTitle;
+    const fallbackDescription = isDLQ
         ? "Event exhausted all retries. Manual replay required."
         : "Event verified and queued for processing.";
+    const description = input.message?.trim() ? input.message : fallbackDescription;
     const fields = [];
     if (input.source) {
         fields.push({ name: "Platform", value: input.source, inline: true });

package/dist/notifications/channels/slack/build-payload.js

@@ -5,10 +5,12 @@ const utils_1 = require("../../utils");
 const constants_1 = require("../../constants");
 function buildSlackPayload(input) {
     const isDLQ = input.dlq;
-    const title = isDLQ ? "Dead Letter Queue — Event Failed" : "Webhook Received";
-    const message = isDLQ
+    const fallbackTitle = isDLQ ? "Dead Letter Queue — Event Failed" : "Webhook Received";
+    const title = input.title?.trim() ? input.title : fallbackTitle;
+    const fallbackMessage = isDLQ
         ? "Event exhausted all retries. Manual replay required."
         : "Event verified and queued for processing.";
+    const message = input.message?.trim() ? input.message : fallbackMessage;
     const fields = [
         input.source
             ? { type: "mrkdwn", text: `*Platform*\n${input.source}` }

package/dist/notifications/constants.d.ts

@@ -1,8 +1,8 @@
 import type { AlertSeverity } from './types';
 export declare const TERN_BRAND_URL = "https://tern.hookflo.com";
-export declare const DEFAULT_DLQ_TITLE = "DLQ Event Alert";
-export declare const DEFAULT_ALERT_TITLE = "Webhook Event Alert";
+export declare const DEFAULT_DLQ_TITLE = "Dead Letter Queue \u2014 Event Failed";
+export declare const DEFAULT_ALERT_TITLE = "Webhook Received";
 export declare const DEFAULT_REPLAY_LABEL = "Replay DLQ Event";
-export declare const DEFAULT_DLQ_MESSAGE = "Webhook event moved to DLQ after retry attempts.";
-export declare const DEFAULT_ALERT_MESSAGE = "Webhook event received.";
+export declare const DEFAULT_DLQ_MESSAGE = "Event exhausted all retries. Manual replay required.";
+export declare const DEFAULT_ALERT_MESSAGE = "Event verified and queued for processing.";
 export declare const severityColorMap: Record<AlertSeverity, string>;

package/dist/notifications/constants.js

@@ -2,11 +2,11 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.severityColorMap = exports.DEFAULT_ALERT_MESSAGE = exports.DEFAULT_DLQ_MESSAGE = exports.DEFAULT_REPLAY_LABEL = exports.DEFAULT_ALERT_TITLE = exports.DEFAULT_DLQ_TITLE = exports.TERN_BRAND_URL = void 0;
 exports.TERN_BRAND_URL = 'https://tern.hookflo.com';
-exports.DEFAULT_DLQ_TITLE = 'DLQ Event Alert';
-exports.DEFAULT_ALERT_TITLE = 'Webhook Event Alert';
+exports.DEFAULT_DLQ_TITLE = 'Dead Letter Queue — Event Failed';
+exports.DEFAULT_ALERT_TITLE = 'Webhook Received';
 exports.DEFAULT_REPLAY_LABEL = 'Replay DLQ Event';
-exports.DEFAULT_DLQ_MESSAGE = 'Webhook event moved to DLQ after retry attempts.';
-exports.DEFAULT_ALERT_MESSAGE = 'Webhook event received.';
+exports.DEFAULT_DLQ_MESSAGE = 'Event exhausted all retries. Manual replay required.';
+exports.DEFAULT_ALERT_MESSAGE = 'Event verified and queued for processing.';
 exports.severityColorMap = {
     info: '#3B82F6',
     warning: '#F59E0B',

package/dist/notifications/dispatch.d.ts

@@ -0,0 +1,8 @@
+import type { AlertConfig, SendAlertOptions } from './types';
+export interface DispatchWebhookAlertInput {
+    alerts?: AlertConfig;
+    source?: string;
+    eventId?: string;
+    alert?: Omit<SendAlertOptions, 'dlq' | 'dlqId' | 'source' | 'eventId'>;
+}
+export declare function dispatchWebhookAlert(input: DispatchWebhookAlertInput): Promise<void>;

package/dist/notifications/dispatch.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dispatchWebhookAlert = dispatchWebhookAlert;
+const send_alert_1 = require("./send-alert");
+async function dispatchWebhookAlert(input) {
+    if (!input.alerts)
+        return;
+    await (0, send_alert_1.sendAlert)(input.alerts, {
+        ...(input.alert || {}),
+        source: input.source,
+        eventId: input.eventId,
+    });
+}

package/dist/notifications/utils.js

@@ -16,29 +16,40 @@ function asNonEmptyString(value) {
 function asObject(value) {
     return value && typeof value === 'object' ? value : undefined;
 }
+function pickNonEmptyString(...values) {
+    for (const value of values) {
+        const normalized = asNonEmptyString(value);
+        if (normalized)
+            return normalized;
+    }
+    return undefined;
+}
+function resolveSourceFromObject(value) {
+    const object = asObject(value);
+    if (!object)
+        return undefined;
+    return pickNonEmptyString(object.platform, object.provider, object.source, object.service, object.origin, object.type);
+}
+function resolveEventIdFromObject(value) {
+    const object = asObject(value);
+    if (!object)
+        return undefined;
+    return pickNonEmptyString(object.eventId, object.event_id, object.id, object.request_id, object.webhook_id, object.messageId, object.message_id);
+}
 function resolveSource(options) {
     const metadata = options.metadata || {};
-    return asNonEmptyString(options.source)
-        || asNonEmptyString(metadata.source)
-        || asNonEmptyString(metadata.platform)
-        || asNonEmptyString(metadata.provider);
+    const metadataPayload = asObject(metadata.payload);
+    const metadataEvent = asObject(metadata.event);
+    const metadataData = asObject(metadata.data);
+    const metadataBody = asObject(metadata.body);
+    return pickNonEmptyString(options.source, metadata.source, metadata.platform, metadata.provider, metadata.eventSource, resolveSourceFromObject(metadataPayload), resolveSourceFromObject(metadataEvent), resolveSourceFromObject(metadataData), resolveSourceFromObject(metadataBody));
 }
 function resolveEventId(options) {
     const metadata = options.metadata || {};
     const metadataPayload = asObject(metadata.payload);
     const metadataEvent = asObject(metadata.event);
     const metadataData = asObject(metadata.data);
-    return asNonEmptyString(options.eventId)
-        || asNonEmptyString(options.dlqId)
-        || asNonEmptyString(metadata.eventId)
-        || asNonEmptyString(metadata.messageId)
-        || asNonEmptyString(metadata.webhookId)
-        || asNonEmptyString(metadata.id)
-        || asNonEmptyString(metadataPayload?.id)
-        || asNonEmptyString(metadataPayload?.eventId)
-        || asNonEmptyString(metadataPayload?.request_id)
-        || asNonEmptyString(metadataEvent?.id)
-        || asNonEmptyString(metadataData?.id);
+    return pickNonEmptyString(options.eventId, options.dlqId, metadata.eventId, metadata.event_id, metadata.messageId, metadata.message_id, metadata.webhookId, metadata.webhook_id, metadata.id, resolveEventIdFromObject(metadataPayload), resolveEventIdFromObject(metadataEvent), resolveEventIdFromObject(metadataData));
 }
 function resolveDestinations(config) {
     const destinations = [];
@@ -59,7 +70,7 @@ function normalizeAlertOptions(options) {
     return {
         ...options,
         dlq: isDlq,
-        source: resolveSource(options),
+        source: resolveSource(options) || 'unknown',
         title,
         message,
         severity,

package/dist/upstash/controls.js

@@ -52,6 +52,9 @@ function deriveStatus(value) {
         return 'failed';
     return 'retrying';
 }
+function withoutUndefined(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, entryValue]) => entryValue !== undefined));
+}
 function createTernControls(config) {
     return {
         async dlq() {
@@ -166,12 +169,12 @@ function createTernControls(config) {
                 ...options,
                 source: resolvedSource,
                 eventId: resolvedEventId || options.dlqId,
-                metadata: {
+                metadata: withoutUndefined({
                     ...(options.metadata || {}),
                     source: resolvedSource || options.metadata?.source,
                     eventId: resolvedEventId || options.metadata?.eventId,
                     ...replayMeta,
-                },
+                }),
             });
         },
     };

package/dist/upstash/queue.js

@@ -194,7 +194,11 @@ async function handleReceive(request, platform, secret, queueConfig, toleranceIn
     }
     try {
         await client.publishJSON(publishPayload);
-        return new Response(JSON.stringify({ queued: true }), {
+        return new Response(JSON.stringify({
+            queued: true,
+            platform,
+            eventId: verificationResult.eventId,
+        }), {
             status: 200,
             headers: { 'Content-Type': 'application/json' },
         });

package/package.json

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