WorkflowController

NestJS controller that handles the well-known workflow endpoints under .well-known/workflow/v1. It dynamically imports the generated workflow bundles and converts between Express/Fastify requests and the Web API Request/Response objects the workflow runtime expects. Both the Express and Fastify HTTP adapters are supported.

The conversion preserves bytes in both directions. WorkflowModule keeps the application's body parsers off these routes, so the request body is normally read straight from the stream; a req.rawBody left by { rawBody: true }, or a Buffer/string body left by a parser, is used when one is present. Responses are written as bytes, and every set-cookie value is kept. See Request bodies and body parsers.

Handlers take @Res() and write the response themselves, so an interceptor or exception filter cannot reshape it. That is deliberate: the queue and third-party webhook senders key off the exact status and body the workflow runtime produces.

Guards do run, because NestJS runs them before the handler. A global guard that rejects unauthenticated requests rejects queue deliveries too; see isWorkflowRequest.

The controller is registered as VERSION_NEUTRAL, so app.enableVersioning() does not move these routes away from the paths the SDK generates URLs for. A global prefix does apply, and WorkflowModule adopts it automatically.

WorkflowModule.forRoot() registers this controller automatically. You only register it yourself if you are not using WorkflowModule.

Usage

When registering the controller manually, call configureWorkflowController first so it can locate the generated bundles; its route handlers throw otherwise.

import { join } from "node:path";
import { Module } from "@nestjs/common";
import {
  configureWorkflowController,
  WorkflowController,
} from "workflow/nest";

configureWorkflowController(join(process.cwd(), ".nestjs/workflow"));

@Module({
  controllers: [WorkflowController],
})
export class AppModule {}

Routes

A route whose bundle cannot be loaded answers 503 with a message naming the missing file and the build command that produces it, rather than surfacing a raw ERR_MODULE_NOT_FOUND.