fix(webhook-engine,webapp): skip Redis and worker setup when the feature is disabled

The engine singleton is constructed at boot, opening the front-gate Redis client
and the worker's queue (a second Redis client plus queue-size gauges) regardless
of WEBHOOK_ENABLED. Only worker.start() was flag-gated, so a deployment with
webhooks off still held two Redis connections and polled queue size, and one
without the webhook Redis configured would spam reconnect errors.

Add an engine-level disabled option (set from WEBHOOK_ENABLED !== '1') that skips
building the Redis clients and the worker entirely. The public entry points
(ingest, simulateInject, replayDelivery, getJob) assert the engine is enabled and
quit() no-ops, so an off deployment is genuinely inert. worker.disabled is
unchanged: an ingress-only instance still builds the engine but does not start the
worker loop.

Author: ericallam

apps/webapp/app/v3/webhookEngine.server.ts

@@ -41,6 +41,7 @@ function createWebhookEngine() {
   const engine = new WebhookEngine({
     prisma: webhookPrisma,
     logLevel: env.WEBHOOK_ENGINE_LOG_LEVEL,
+    disabled: env.WEBHOOK_ENABLED !== "1",
     redis: {
       host: env.WEBHOOK_WORKER_REDIS_HOST ?? "localhost",
       port: env.WEBHOOK_WORKER_REDIS_PORT ?? 6379,

internal-packages/webhook-engine/src/engine/disabled.test.ts

@@ -0,0 +1,37 @@
+import type { WebhookDatabase } from "@trigger.dev/database";
+import { describe, expect, it } from "vitest";
+import { WebhookEngine } from "./index.js";
+import type { TriggerWebhookTaskCallback } from "./types.js";
+
+const triggerTask: TriggerWebhookTaskCallback = async () => ({ success: true });
+
+function buildDisabledEngine() {
+  return new WebhookEngine({
+    prisma: {} as unknown as WebhookDatabase,
+    disabled: true,
+    redis: { host: "127.0.0.1", port: 6379 },
+    worker: { concurrency: 1 },
+    triggerTask,
+    resolveSigningSecret: async () => undefined,
+    logLevel: "error",
+  });
+}
+
+describe("WebhookEngine (disabled)", () => {
+  it("skips Redis and worker setup, and rejects public calls", async () => {
+    const engine = buildDisabledEngine();
+
+    await expect(
+      engine.ingest({
+        opaqueId: "x",
+        rawBytes: new TextEncoder().encode("{}"),
+        headers: {},
+        url: "https://example.com/webhooks/v1/ingest/x",
+      })
+    ).rejects.toThrow(/disabled/i);
+
+    await expect(engine.getJob("job")).rejects.toThrow(/disabled/i);
+
+    await expect(engine.quit()).resolves.toBeUndefined();
+  });
+});

internal-packages/webhook-engine/src/engine/index.ts

@@ -34,7 +34,7 @@ import { evaluateSessionKeyTemplate, walkPath as resolveBodyPath } from "./sessi
 const WEBHOOK_DELIVER_MAX_ATTEMPTS = webhookWorkerCatalog["webhook.deliver"].retry.maxAttempts;
 
 export class WebhookEngine {
-  private worker: Worker<typeof webhookWorkerCatalog>;
+  private worker!: Worker<typeof webhookWorkerCatalog>;
   private logger: Logger;
   private tracer: Tracer;
   private meter: Meter;
@@ -50,7 +50,7 @@ export class WebhookEngine {
   prisma: WebhookDatabase;
 
   private triggerTask: TriggerWebhookTaskCallback;
-  private frontGate: Redis;
+  private frontGate!: Redis;
   // Caches the endpoint + resolved signing secret per opaqueId so the ingest hot path skips two
   // Postgres reads (endpoint lookup + secret decrypt). Both are immutable per endpoint within the
   // TTL; a status change or secret rotation takes effect after at most the TTL.
@@ -61,7 +61,6 @@ export class WebhookEngine {
       options.logger ?? new Logger("WebhookEngine", (this.options.logLevel ?? "info") as any);
     this.prisma = options.prisma;
     this.triggerTask = options.triggerTask;
-    this.frontGate = createRedisClient(options.redis);
 
     this.tracer = options.tracer ?? getTracer("webhook-engine");
     this.meter = options.meter ?? getMeter("webhook-engine");
@@ -96,6 +95,13 @@ export class WebhookEngine {
       options.endpointCache?.maxSize ?? 10_000
     );
 
+    if (options.disabled) {
+      this.logger.info("Webhook engine disabled; skipping Redis and worker setup");
+      return;
+    }
+
+    this.frontGate = createRedisClient(options.redis);
+
     this.worker = new Worker({
       name: "webhook-engine-worker",
       redisOptions: {
@@ -137,8 +143,15 @@ export class WebhookEngine {
     }
   }
 
+  #assertEnabled(): void {
+    if (this.options.disabled) {
+      throw new Error('WebhookEngine is disabled: WEBHOOK_ENABLED is not "1"');
+    }
+  }
+
   // PUBLIC ENTRY: verify inline, append-only delivery write, enqueue routing, ack.
   async ingest(input: IngestInput): Promise<IngestResult> {
+    this.#assertEnabled();
     return startSpan(this.tracer, "webhook.ingest", async (span) => {
       span.setAttribute("opaqueId", input.opaqueId);
 
@@ -317,6 +330,7 @@ export class WebhookEngine {
    * downstream (filter, startOn, routing, run/session) runs for real.
    */
   async simulateInject(input: IngestInput): Promise<IngestResult> {
+    this.#assertEnabled();
     return startSpan(this.tracer, "webhook.simulate", async (span) => {
       span.setAttribute("opaqueId", input.opaqueId);
 
@@ -354,6 +368,7 @@ export class WebhookEngine {
   // fresh idempotency key is created so the run actually executes (not deduped) and the replay is
   // auditable; it shares the original externalDeliveryId so the two group together.
   async replayDelivery(input: { id: string; createdAt: Date }): Promise<ReplayResult> {
+    this.#assertEnabled();
     return startSpan(this.tracer, "webhook.replay", async (span) => {
       span.setAttribute("deliveryId", input.id);
 
@@ -748,10 +763,12 @@ export class WebhookEngine {
   }
 
   async getJob(id: string) {
+    this.#assertEnabled();
     return this.worker.getJob(id);
   }
 
   async quit() {
+    if (this.options.disabled) return;
     this.logger.info("Shutting down webhook engine");
 
     try {

internal-packages/webhook-engine/src/engine/types.ts

@@ -30,6 +30,13 @@ export interface WebhookEngineOptions {
   logLevel?: string;
   prisma: WebhookDatabase;
   redis: RedisOptions;
+  /**
+   * When true the feature is fully off: the engine skips opening its Redis clients and building the
+   * worker, so a deployment with webhooks disabled holds no connections and does no queue polling.
+   * Distinct from `worker.disabled`, which keeps the engine (and its front-gate Redis) for ingress
+   * but does not start the worker loop.
+   */
+  disabled?: boolean;
   worker: {
     concurrency: number;
     workers?: number;