bunqueue 2.8.8 → 2.8.10

package/dist/client/forwarder.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Forwarder — store-and-forward from a local (edge) queue to a remote
+ * bunqueue server.
+ *
+ * The edge pattern: jobs buffer in the local queue (typically embedded
+ * SQLite on a gateway); the Forwarder drains them to a central server over
+ * TCP/TLS. A remote failure makes the local job fail → local retry/backoff →
+ * local DLQ, so nothing is lost while the uplink is down.
+ *
+ * Idempotency: every forwarded job carries the deterministic remote jobId
+ * `fwd:<localQueueKey>:<localJobId>`. The server dedupes custom jobIds, so a
+ * re-forward after a crash or retry never duplicates the job remotely.
+ */
+import { EventEmitter } from 'events';
+import type { ConnectionOptions, QueueOptions } from './types';
+/** Options for queue.forward() */
+export interface ForwardOptions {
+    /** Remote server connection (host/port/tls/token...) */
+    to: ConnectionOptions;
+    /** Remote queue name (default: same as the source queue) */
+    queue?: string;
+    /** Parallel forwards (default: 4) */
+    concurrency?: number;
+    /** Push to the remote with durable: true (immediate fsync server-side) */
+    durable?: boolean;
+}
+/** Source queue identity + config, provided by Queue.forward() */
+export interface ForwardSource {
+    /** Logical source queue name */
+    name: string;
+    /** Source queue key (prefixKey + name) — used in the deterministic jobId */
+    queueKey: string;
+    prefixKey?: string;
+    embedded: boolean;
+    dataPath?: string;
+    connection?: ConnectionOptions;
+}
+/** Minimal remote-queue surface the Forwarder needs (avoids a Queue import cycle) */
+interface RemoteQueueLike {
+    add(name: string, data: unknown, opts?: {
+        jobId?: string;
+        priority?: number;
+        durable?: boolean;
+    }): Promise<unknown>;
+    close(): Promise<void> | void;
+}
+/** Constructor for the remote queue, injected by Queue.forward() */
+export type RemoteQueueCtor = new (name: string, opts: QueueOptions) => RemoteQueueLike;
+/** Info emitted with each 'forwarded' event */
+export interface ForwardedInfo {
+    /** Local job id */
+    id: string;
+    /** Deterministic remote job id (fwd:<queueKey>:<id>) */
+    remoteId: string;
+    /** Job name */
+    name: string;
+}
+/**
+ * Drains a local queue into a remote bunqueue server.
+ * Create via `queue.forward(options)`; stop with `close()`.
+ */
+export declare class Forwarder extends EventEmitter {
+    on(event: 'forwarded', listener: (info: ForwardedInfo) => void): this;
+    on(event: 'error', listener: (error: Error) => void): this;
+    private readonly remote;
+    private readonly worker;
+    private closed;
+    constructor(source: ForwardSource, options: ForwardOptions, RemoteQueue: RemoteQueueCtor);
+    /** Stop forwarding and release connections. Safe to call more than once. */
+    close(): Promise<void>;
+}
+export {};

package/dist/client/forwarder.js

@@ -0,0 +1,79 @@
+/**
+ * Forwarder — store-and-forward from a local (edge) queue to a remote
+ * bunqueue server.
+ *
+ * The edge pattern: jobs buffer in the local queue (typically embedded
+ * SQLite on a gateway); the Forwarder drains them to a central server over
+ * TCP/TLS. A remote failure makes the local job fail → local retry/backoff →
+ * local DLQ, so nothing is lost while the uplink is down.
+ *
+ * Idempotency: every forwarded job carries the deterministic remote jobId
+ * `fwd:<localQueueKey>:<localJobId>`. The server dedupes custom jobIds, so a
+ * re-forward after a crash or retry never duplicates the job remotely.
+ */
+import { EventEmitter } from 'events';
+import { Worker } from './worker';
+/**
+ * Drains a local queue into a remote bunqueue server.
+ * Create via `queue.forward(options)`; stop with `close()`.
+ */
+export class Forwarder extends EventEmitter {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    on(event, listener) {
+        return super.on(event, listener);
+    }
+    remote;
+    worker;
+    closed = false;
+    constructor(source, options, RemoteQueue) {
+        super();
+        this.remote = new RemoteQueue(options.queue ?? source.name, {
+            embedded: false,
+            connection: options.to,
+            autoBatch: { enabled: false },
+        });
+        this.worker = new Worker(source.name, async (job) => {
+            const remoteId = `fwd:${source.queueKey}:${job.id}`;
+            await this.remote.add(job.name, job.data, {
+                jobId: remoteId,
+                ...(job.opts.priority !== undefined && { priority: job.opts.priority }),
+                ...(options.durable && { durable: true }),
+            });
+            const info = { id: job.id, remoteId, name: job.name };
+            // A throwing user listener must not fail a forward that already
+            // succeeded remotely (it would trigger a local retry of a done job).
+            try {
+                this.emit('forwarded', info);
+            }
+            catch {
+                /* listener error — forward itself succeeded */
+            }
+            return info;
+        }, {
+            embedded: source.embedded,
+            dataPath: source.dataPath,
+            connection: source.connection,
+            prefixKey: source.prefixKey,
+            concurrency: options.concurrency ?? 4,
+        });
+        // A remote failure is already handled by the local retry/DLQ path; the
+        // event is observability. Guard: EventEmitter throws on 'error' without
+        // listeners, and a transient uplink failure must never crash the process.
+        this.worker.on('failed', (_job, err) => {
+            if (this.listenerCount('error') > 0)
+                this.emit('error', err);
+        });
+        this.worker.on('error', (err) => {
+            if (this.listenerCount('error') > 0)
+                this.emit('error', err);
+        });
+    }
+    /** Stop forwarding and release connections. Safe to call more than once. */
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        await this.worker.close();
+        await this.remote.close();
+    }
+}

package/dist/client/index.d.ts

@@ -26,6 +26,8 @@ export { Worker } from './worker';
 export { Bunqueue } from './bunqueue';
 export type { BunqueueOptions, BunqueueMiddleware, RetryStrategy, RetryConfig, CircuitBreakerConfig, TriggerRule, PriorityAgingConfig, BatchProcessor, BatchConfig, JobTtlConfig, BunqueueDeduplicationConfig, BunqueueDebounceConfig, BunqueueDlqConfig, } from './bunqueue';
 export { SandboxedWorker } from './sandboxedWorker';
+export { Forwarder } from './forwarder';
+export type { ForwardOptions, ForwardedInfo } from './forwarder';
 export { QueueEvents } from './events';
 export { QueueGroup } from './queueGroup';
 export { FlowProducer } from './flow';

package/dist/client/index.js

@@ -25,6 +25,7 @@ export { Queue } from './queue';
 export { Worker } from './worker';
 export { Bunqueue } from './bunqueue';
 export { SandboxedWorker } from './sandboxedWorker';
+export { Forwarder } from './forwarder';
 export { QueueEvents } from './events';
 export { QueueGroup } from './queueGroup';
 export { FlowProducer } from './flow';

package/dist/client/queue/queue.d.ts

@@ -3,6 +3,7 @@
  * BullMQ-style queue for job management
  */
 import type { Job, JobOptions, QueueOptions, StallConfig, DlqConfig, DlqEntry, DlqStats, DlqFilter, ChangePriorityOpts, GetDependenciesOpts, JobDependencies, JobDependenciesCount, JobStateType } from '../types';
+import { Forwarder, type ForwardOptions } from '../forwarder';
 import * as countsOps from './operations/counts';
 import * as schedulerOps from './scheduler';
 import type { RepeatOpts, JobTemplate, SchedulerInfo } from './scheduler';
@@ -168,6 +169,14 @@ export declare class Queue<T = unknown> {
         };
         data: number[];
     }>;
+    /**
+     * Drain this queue's jobs to a remote bunqueue server (store-and-forward).
+     * Typical edge pattern: embedded local queue as offline buffer, forwarded
+     * to a central server over TCP/TLS. Remote failures leave jobs local
+     * (retry → DLQ) — nothing is lost while the uplink is down. Forwarded jobs
+     * carry a deterministic remote jobId so re-forwards never duplicate.
+     */
+    forward(options: ForwardOptions): Forwarder;
     disconnect(): Promise<void>;
     close(): void;
 }

package/dist/client/queue/queue.js

@@ -5,6 +5,7 @@
 import { TcpConnectionPool, getSharedPool, releaseSharedPool } from '../tcpPool';
 import { FORCE_EMBEDDED } from './helpers';
 import { AddBatcher } from './addBatcher';
+import { Forwarder } from '../forwarder';
 import { resolveToken } from '../resolveToken';
 import { getSharedManager } from '../manager';
 // Import operation modules
@@ -483,6 +484,24 @@ export class Queue {
     getMetrics(type, start, end) {
         return workersOps.getMetrics(this.ctx, type, start, end);
     }
+    // ============ Forwarding ============
+    /**
+     * Drain this queue's jobs to a remote bunqueue server (store-and-forward).
+     * Typical edge pattern: embedded local queue as offline buffer, forwarded
+     * to a central server over TCP/TLS. Remote failures leave jobs local
+     * (retry → DLQ) — nothing is lost while the uplink is down. Forwarded jobs
+     * carry a deterministic remote jobId so re-forwards never duplicate.
+     */
+    forward(options) {
+        return new Forwarder({
+            name: this.name,
+            queueKey: this.queueKey,
+            prefixKey: this.prefixKey || undefined,
+            embedded: this.embedded,
+            dataPath: this.opts.dataPath,
+            connection: this.opts.connection,
+        }, options, Queue);
+    }
     // ============ Connection ============
     async disconnect() {
         if (this.addBatcher) {

package/dist/domain/types/cron.js

@@ -16,7 +16,9 @@ export function createCronJob(input, nextRun) {
         timezone: input.timezone ?? null,
         nextRun,
         executions: 0,
-        maxLimit: input.maxLimit ?? null,
+        // 0/negative mean "no limit" on every surface (CLI/HTTP/TCP/MCP): storing
+        // 0 would make isAtLimit treat the cron as already exhausted (0 >= 0).
+        maxLimit: input.maxLimit !== undefined && input.maxLimit > 0 ? input.maxLimit : null,
         uniqueKey: input.uniqueKey ?? null,
         dedup: input.dedup ?? null,
         skipMissedOnRestart: input.skipMissedOnRestart ?? true,

package/dist/domain/types/webhook.d.ts

@@ -3,8 +3,18 @@
  */
 /** Webhook ID type */
 export type WebhookId = string;
-/** Webhook event types */
-export type WebhookEvent = 'job.pushed' | 'job.started' | 'job.completed' | 'job.failed' | 'job.progress' | 'job.stalled';
+/**
+ * Canonical list of webhook events the server actually triggers — single
+ * source of truth for CLI/TCP/HTTP/MCP validation. job.pushed/started/
+ * completed/failed flow through eventsManager.mapEventToWebhook; job.progress
+ * is triggered directly by updateProgress (jobManagement).
+ */
+export declare const WEBHOOK_EVENTS: readonly ["job.pushed", "job.started", "job.completed", "job.failed", "job.progress"];
+/**
+ * Webhook event types. Includes 'job.stalled' for backward compatibility with
+ * stored webhooks, but it is never emitted and not accepted on new ones.
+ */
+export type WebhookEvent = (typeof WEBHOOK_EVENTS)[number] | 'job.stalled';
 /** Webhook configuration */
 export interface Webhook {
     id: WebhookId;

package/dist/domain/types/webhook.js

@@ -2,6 +2,19 @@
  * Webhook domain types
  */
 import { uuid } from '../../shared/hash';
+/**
+ * Canonical list of webhook events the server actually triggers — single
+ * source of truth for CLI/TCP/HTTP/MCP validation. job.pushed/started/
+ * completed/failed flow through eventsManager.mapEventToWebhook; job.progress
+ * is triggered directly by updateProgress (jobManagement).
+ */
+export const WEBHOOK_EVENTS = [
+    'job.pushed',
+    'job.started',
+    'job.completed',
+    'job.failed',
+    'job.progress',
+];
 /** Create a new webhook */
 export function createWebhook(url, events, queue, secret) {
     return {

package/dist/infrastructure/server/bootstrap.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Server bootstrap — the ONE place that boots a full bunqueue server.
+ * Used by both entry points (`bunqueue` bare via main.ts and
+ * `bunqueue start` via the CLI) so they cannot drift: S3 backup, cloud
+ * agent, stats interval, crash handlers and graceful shutdown are always on.
+ */
+import { type BunqueueConfig, type ResolvedConfig } from '../../config';
+/** Boot the full server from resolved configuration. Runs until shutdown. */
+export declare function bootServer(fileConfig: BunqueueConfig | null, config: ResolvedConfig): void;

package/dist/infrastructure/server/bootstrap.js

@@ -0,0 +1,217 @@
+/**
+ * Server bootstrap — the ONE place that boots a full bunqueue server.
+ * Used by both entry points (`bunqueue` bare via main.ts and
+ * `bunqueue start` via the CLI) so they cannot drift: S3 backup, cloud
+ * agent, stats interval, crash handlers and graceful shutdown are always on.
+ */
+import { QueueManager } from '../../application/queueManager';
+import { createTcpServer } from './tcp';
+import { createHttpServer } from './http';
+import { Logger, serverLog, statsLog } from '../../shared/logger';
+import { stopRateLimiter } from './rateLimiter';
+import { VERSION } from '../../shared/version';
+import { S3BackupManager } from '../backup';
+import { CloudAgent } from '../cloud';
+import { SHARD_COUNT } from '../../shared/hash';
+import { resolveCloudConfig, resolveBackupConfig, resolveTlsServerOptions, } from '../../config';
+/** Print startup banner */
+function printBanner(config, cloudUrl) {
+    const dim = '\x1b[2m';
+    const reset = '\x1b[0m';
+    const bold = '\x1b[1m';
+    const magenta = '\x1b[35m';
+    const green = '\x1b[32m';
+    const yellow = '\x1b[33m';
+    // Format TCP endpoint display
+    const tcpDisplay = config.tcpSocketPath
+        ? `${bold}${config.tcpSocketPath}${reset} ${dim}(unix)${reset}`
+        : `${bold}${config.hostname}:${config.tcpPort}${reset}`;
+    // Format HTTP endpoint display
+    const httpDisplay = config.httpSocketPath
+        ? `${bold}${config.httpSocketPath}${reset} ${dim}(unix)${reset}`
+        : `${bold}${config.hostname}:${config.httpPort}${reset}`;
+    // Socket mode display
+    const hasUnixSockets = config.tcpSocketPath !== undefined || config.httpSocketPath !== undefined;
+    const socketDisplay = hasUnixSockets
+        ? `${green}enabled${reset} ${dim}(${config.tcpSocketPath ? 'TCP' : ''}${config.tcpSocketPath && config.httpSocketPath ? '+' : ''}${config.httpSocketPath ? 'HTTP' : ''})${reset}`
+        : `${dim}disabled${reset}`;
+    console.log(`
+${magenta}        (\\(\\        ${reset}
+${magenta}        ( -.-)      ${bold}bunqueue${reset} ${dim}v${VERSION}${reset}
+${magenta}        o_(")(")    ${reset}${dim}High-performance job queue for Bun${reset}
+
+${dim}─────────────────────────────────────────────────${reset}
+
+  ${green}●${reset} TCP    ${tcpDisplay}
+  ${green}●${reset} HTTP   ${httpDisplay}
+  ${yellow}●${reset} Socket ${socketDisplay}
+  ${yellow}●${reset} Data   ${config.dataPath ?? 'in-memory'}
+  ${yellow}●${reset} TLS    ${config.tlsCertFile ? `${green}enabled${reset}` : `${dim}disabled${reset}`}
+  ${yellow}●${reset} Auth   ${config.authTokens.length > 0 ? `${green}enabled${reset}` : `${dim}disabled${reset}`}
+  ${yellow}●${reset} S3 Backup ${config.s3BackupEnabled ? `${green}enabled${reset}` : `${dim}disabled${reset}`}
+  ${yellow}●${reset} Cloud  ${cloudUrl ? `${green}enabled${reset} ${dim}→ ${cloudUrl}${reset}` : `${dim}disabled${reset}`}
+  ${dim}●${reset} Shards ${bold}${SHARD_COUNT}${reset} ${dim}(${navigator.hardwareConcurrency} CPU cores)${reset}
+
+${dim}─────────────────────────────────────────────────${reset}
+
+`);
+}
+/** Boot the full server from resolved configuration. Runs until shutdown. */
+export function bootServer(fileConfig, config) {
+    // Apply logging config before anything else
+    const logFormat = fileConfig?.logging?.format ?? Bun.env.LOG_FORMAT;
+    const logLevel = fileConfig?.logging?.level ?? Bun.env.LOG_LEVEL?.toLowerCase();
+    if (logFormat === 'json')
+        Logger.enableJsonMode();
+    if (logLevel) {
+        const validLevels = ['debug', 'info', 'warn', 'error'];
+        if (validLevels.includes(logLevel))
+            Logger.setLevel(logLevel);
+    }
+    // Resolve cloud config
+    const cloudConfig = resolveCloudConfig(fileConfig, config.dataPath);
+    // Resolve TLS config — fail fast on partial cert/key before binding anything
+    let tlsConfig;
+    try {
+        tlsConfig = resolveTlsServerOptions(config);
+    }
+    catch (err) {
+        serverLog.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+    printBanner(config, cloudConfig?.url);
+    // Create queue manager
+    const queueManager = new QueueManager({
+        dataPath: config.dataPath,
+    });
+    // Start TCP + HTTP servers; a bind failure must not leave a half-started process
+    let tcpServer;
+    let httpServer;
+    try {
+        tcpServer = createTcpServer(queueManager, {
+            port: config.tcpPort,
+            hostname: config.hostname,
+            authTokens: config.authTokens,
+            ...(tlsConfig && { tls: tlsConfig }),
+        });
+        httpServer = createHttpServer(queueManager, {
+            port: config.httpPort,
+            hostname: config.hostname,
+            socketPath: config.httpSocketPath,
+            authTokens: config.authTokens,
+            corsOrigins: config.corsOrigins,
+            requireAuthForMetrics: config.requireAuthForMetrics,
+            ...(tlsConfig && { tls: tlsConfig }),
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : 'Unknown error';
+        console.error(`Failed to start server: ${msg}`);
+        queueManager.shutdown();
+        process.exit(1);
+    }
+    // Initialize S3 backup manager
+    let backupManager = null;
+    if (config.dataPath) {
+        const backupConfig = resolveBackupConfig(fileConfig, config.dataPath);
+        backupManager = new S3BackupManager(backupConfig);
+        backupManager.setDashboardEmit(queueManager.emitDashboardEvent.bind(queueManager));
+        backupManager.start();
+    }
+    // Initialize bunqueue Cloud agent (remote dashboard telemetry)
+    const cloudAgent = cloudConfig ? CloudAgent.createFromConfig(queueManager, cloudConfig) : null;
+    if (cloudAgent) {
+        cloudAgent.setServerHandles({
+            getConnectionCount: () => tcpServer.getConnectionCount(),
+            getWsClientCount: () => httpServer.getWsClientCount(),
+            getSseClientCount: () => httpServer.getSseClientCount(),
+            getBackupStatus: () => backupManager?.getStatus() ?? null,
+        });
+    }
+    queueManager.emitDashboardEvent('server:started', {
+        tcpPort: config.tcpPort,
+        httpPort: config.httpPort,
+        shards: SHARD_COUNT,
+    });
+    // Graceful shutdown
+    let shuttingDown = false;
+    const shutdown = async (signal) => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        serverLog.info(`Received ${signal}, shutting down...`);
+        // Stop stats interval immediately
+        clearInterval(statsInterval);
+        tcpServer.stop();
+        httpServer.stop();
+        const shutdownTimeout = config.shutdownTimeoutMs;
+        const start = Date.now();
+        while (Date.now() - start < shutdownTimeout) {
+            const stats = queueManager.getStats();
+            if (stats.active === 0)
+                break;
+            serverLog.info(`Waiting for ${stats.active} active jobs...`);
+            await Bun.sleep(1000);
+        }
+        // Stop backup manager
+        if (backupManager) {
+            backupManager.stop();
+        }
+        // Stop Cloud agent (sends final shutdown snapshot)
+        if (cloudAgent) {
+            await cloudAgent.stop();
+        }
+        queueManager.emitDashboardEvent('server:shutdown', { signal });
+        queueManager.shutdown();
+        stopRateLimiter();
+        serverLog.info('Shutdown complete');
+        process.exit(0);
+    };
+    process.on('SIGINT', () => void shutdown('SIGINT'));
+    process.on('SIGTERM', () => void shutdown('SIGTERM'));
+    process.on('uncaughtException', (err) => {
+        serverLog.error('Uncaught exception - initiating shutdown', {
+            error: err.message,
+            stack: err.stack,
+        });
+        void shutdown('uncaughtException');
+    });
+    process.on('unhandledRejection', (reason) => {
+        serverLog.error('Unhandled promise rejection - initiating shutdown', {
+            reason: reason instanceof Error ? reason.message : String(reason),
+            stack: reason instanceof Error ? reason.stack : undefined,
+        });
+        void shutdown('unhandledRejection');
+    });
+    // Print stats periodically
+    const statsInterval = setInterval(() => {
+        const stats = queueManager.getStats();
+        const memStats = queueManager.getMemoryStats();
+        const workerStats = queueManager.workerManager.getStats();
+        const mem = process.memoryUsage();
+        const now = new Date();
+        const timestamp = now.toLocaleTimeString('en-GB', {
+            hour: '2-digit',
+            minute: '2-digit',
+            second: '2-digit',
+        });
+        statsLog.info('Queue statistics', {
+            time: timestamp,
+            waiting: stats.waiting,
+            active: stats.active,
+            delayed: stats.delayed,
+            completed: stats.completed,
+            dlq: stats.dlq,
+            tcp: tcpServer.getConnectionCount(),
+            ws: httpServer.getWsClientCount(),
+            sse: httpServer.getSseClientCount(),
+            workers: `${workerStats.active}/${workerStats.total}`,
+            mem: `${Math.round(mem.heapUsed / 1024 / 1024)}MB/${Math.round(mem.heapTotal / 1024 / 1024)}MB`,
+            rss: `${Math.round(mem.rss / 1024 / 1024)}MB`,
+            // Internal collection sizes (for memory debugging)
+            idx: memStats.jobIndex,
+            locks: memStats.jobLocks,
+            clients: memStats.clientJobsTotal,
+        });
+    }, config.statsIntervalMs);
+}

package/dist/infrastructure/server/handlers/advanced.js

@@ -4,6 +4,7 @@
  */
 import * as resp from '../../../domain/types/response';
 import { jobId } from '../../../domain/types/job';
+import { validateNumericField } from '../protocol';
 /**
  * Coerce a value to a finite number, or return undefined if it can't be.
  * Guards config endpoints against non-numeric input (e.g. `"abc"`) that would
@@ -108,6 +109,13 @@ export async function handleDiscard(cmd, ctx, reqId) {
 /** Handle WaitJob command - wait for job completion (event-driven, no polling) */
 export async function handleWaitJob(cmd, ctx, reqId) {
     const jid = jobId(cmd.id);
+    // Bounded like PULL (which caps at 60s); waiting for completion is
+    // legitimately longer, so the cap here is 10 min. validateNumericField also
+    // rejects NaN/Infinity from hostile clients (a hand-rolled <0/>max check
+    // would let NaN through and resolve instantly as a false "not completed").
+    const timeoutError = validateNumericField(cmd.timeout, 'timeout', { min: 0, max: 600000 });
+    if (timeoutError)
+        return resp.error(timeoutError, reqId);
     const timeout = cmd.timeout ?? 30000;
     // First check if job exists and is already completed
     const job = await ctx.queueManager.getJob(jid);

package/dist/infrastructure/server/handlers/monitoring.js

@@ -6,6 +6,7 @@ import { jobId } from '../../../domain/types/job';
 import { VERSION } from '../../../shared/version';
 import * as resp from '../../../domain/types/response';
 import { validateWebhookUrl } from '../protocol';
+import { WEBHOOK_EVENTS } from '../../../domain/types/webhook';
 // ============ Job Logs ============
 export function handleAddLog(cmd, ctx, reqId) {
     const jid = jobId(cmd.id);
@@ -140,6 +141,12 @@ export function handleAddWebhook(cmd, ctx, reqId) {
     const urlError = validateWebhookUrl(cmd.url);
     if (urlError)
         return resp.error(urlError, reqId);
+    // Reject events that are never triggered — a webhook subscribed to a dead
+    // event would be created "ok" and then never fire (silent failure).
+    const invalidEvents = cmd.events.filter((e) => !WEBHOOK_EVENTS.includes(e));
+    if (invalidEvents.length > 0) {
+        return resp.error(`Invalid webhook event(s): ${invalidEvents.join(', ')}. Valid: ${WEBHOOK_EVENTS.join(', ')}`, reqId);
+    }
     const webhook = ctx.queueManager.webhookManager.add(cmd.url, cmd.events, cmd.queue, cmd.secret);
     ctx.queueManager.emitDashboardEvent('webhook:added', {
         id: webhook.id,