Advanced Options

Advanced Options are intended to support edge cases or testing pipelines and are not required for regular use.

failureFunction · string

Defines a function that executes if the workflow fails after all retries are exhausted.

For details, see failureFunction.

TypeScript

export const { POST } = serve<string>(
  async (context) => { ... },
  {
    failureFunction: async ({
      context,      // context during failure
      failStatus,   // failure status
      failResponse, // failure message
      failHeaders   // failure headers
      failStack.    // failure stack trace (if available)
    }) => {
      // handle the failure
    }
  }
);

failureUrl · string

This parameter is only available in Python SDK. In Javascript SDK, you can pass this value when triggering the workflow.

The failureUrl option defines an external endpoint that will be called if the workflow fails after all retries are exhausted.

This option is an advanced alternative to failureFunction. For more details, see Advanced failureUrl Option.

Python

@serve.post("/api/example", failureUrl="https://<YOUR-FAILURE-ENDPOINT>/...")
async def example(context: AsyncWorkflowContext[str]) -> None: ...

retries · number

This parameter is only available in Python SDK. In Javascript SDK, you can pass this value when triggering the workflow.

Defines the number of retry attempts if a workflow step fails. The default value is 3.

For details, see retry configuration.

Python

@serve.post("/api/example", retries=3)
async def example(context: AsyncWorkflowContext[str]) -> None: ...

middlewares · WorkflowMiddleware[]

An array of middleware instances that intercept workflow lifecycle and debug events.

Middlewares allow you to hook into various stages of workflow execution (before/after steps, run start/completion) and debug events (errors, warnings, info logs).

For details and examples, see Middlewares.

TypeScript

import { serve } from "@upstash/workflow/nextjs";
import { loggingMiddleware } from "@upstash/workflow";

export const { POST } = serve<string>(
  async (context) => { ... },
  {
    middlewares: [loggingMiddleware]
  }
);

initialPayloadParser · bool

Enables custom parsing of the initial request payload.

Use this option if the incoming payload is not plain JSON or a simple string. The parser function lets you transform the raw request into a strongly typed object before workflow execution begins.

TypeScript

type InitialPayload = {
  foo: string;
  bar: number;
};

// 👇 1: provide initial payload type
export const { POST } = serve<InitialPayload>(
  async (context) => {
    // 👇 3: parsing result is available as requestPayload
    const payload: InitialPayload = context.requestPayload;
  },
  {
    // 👇 2: custom parsing for initial payload
    initialPayloadParser: (initialPayload) => {
      const payload: InitialPayload = parsePayload(initialPayload);
      return payload;
    },
  }
);

schema · z.ZodType

Alternative to initialPayloadParser, you can pass a schema in the TypeScript SDK.

The schema is used to validate and parse the initial request payload automatically using Zod.

TypeScript

import { z } from "zod";

const parameters = z.object({ expression: z.string() });

export const { POST } = serve(
  async (context) => {
    // context.requestPayload is typed as `{ expression: string }`
    const payload = context.requestPayload;
  },
  {
    schema: parameters,
  }
);

url · string

Specifies the full endpoint URL of the workflow, including the route path.

By default, Upstash Workflow infers the URL from request.url when scheduling the next step. However, in some environments, request.url may resolve to an internal or unreachable address.

Use this option when running behind a proxy, reverse proxy, or local tunnel during development where request.url cannot be used directly.

TypeScript

export const { POST } = serve<string>(
  async (context) => { ... },
  {
    url: "https://<YOUR-DEPLOYED-APP>.com/api/workflow"
  }
);

baseUrl · string

Similar to url, but baseUrl only overrides the base portion of the inferred URL rather than replacing the entire path. This is useful when you want to preserve the route structure while changing only the host or scheme.

If you have multiple workflow endpoints, you can set the UPSTASH_WORKFLOW_URL environment variable instead of configuring baseUrl on each endpoint. The UPSTASH_WORKFLOW_URL environment variable corresponds directly to this option and configures it globally.

TypeScript

export const { POST } = serve<string>(
  async (context) => {
    ...
  },
  // options:
  {
    baseUrl: "<LOCAL-TUNNEL-PUBLIC-URL>"
  }
);

qstashClient · object

Use qstashClient if you want to provide your own QStash client instead of letting Workflow use the default from environment variables.

This is useful if you’re working with multiple QStash projects in the same app.

TypeScript

import { Client } from "@upstash/qstash";
import { serve } from "@upstash/workflow/nextjs";

export const { POST } = serve(
  async (context) => { ... },
  {
    qstashClient: new Client({ token: "<QSTASH_TOKEN>" })
  }
);

receiver · object

The Receiver verifies that every request to your endpoint actually comes from QStash, blocking anyone else from triggering your workflow.

The receiver option allows you to pass a QStash Receiver explicitly.

By default, Workflow initializes the Receiver automatically using the environment variables QSTASH_CURRENT_SIGNING_KEY and QSTASH_NEXT_SIGNING_KEY.

This is useful if you’re working with multiple QStash projects in the same app.

TypeScript

import { Receiver } from "@upstash/qstash";
import { serve } from "@upstash/workflow/nextjs";

export const { POST } = serve<string>(
  async (context) => { ... },
  {
    receiver: new Receiver({
      currentSigningKey: "<QSTASH_CURRENT_SIGNING_KEY>",
      nextSigningKey: "<QSTASH_NEXT_SIGNING_KEY>",
    })
  }
);

env · object

By default, Workflow uses process.env to read credentials and initialize QStash. If you’re in an environment where process.env isn’t available, or you want to inject values manually, you can pass them with env.

Inside your workflow, these values are also exposed on context.env.

TypeScript

import { Receiver } from "@upstash/qstash";
import { serve } from "@upstash/workflow/nextjs";

export const { POST } = serve<string>(
  async (context) => {
    // the env option will be available in the env field of the context:
    const env = context.env;
  },
  {
    env: {
        QSTASH_URL: "<QSTASH_URL>",
        QSTASH_TOKEN: "<QSTASH_TOKEN>",
        QSTASH_CURRENT_SIGNING_KEY: "<QSTASH_CURRENT_SIGNING_KEY>",
        QSTASH_NEXT_SIGNING_KEY: "<QSTASH_NEXT_SIGNING_KEY>",
    }
  }
);

verbose · boolean

Enables verbose mode to print detailed logs of workflow execution to the application’s stdout.

Verbose mode is disabled by default.

export const { POST } = serve<string>(
  async (context) => { ... },
  {
    verbose: true
  }
);

disableTelemetry · boolean

Disables anonymous telemetry data collection for this workflow endpoint. Since we don’t collect telemetry in Python SDK, this option is only available in the TypeScript SDK.

By default, the Upstash Workflow SDK collects anonymous telemetry data to help improve the service. The collected data includes:

• SDK version
• Platform (Vercel, AWS, etc.)
• Runtime version (Node.js, Python, etc.)

Set disableTelemetry to true to opt out of telemetry for this specific workflow endpoint.

TypeScript

export const { POST } = serve<string>(
  async (context) => { ... },
  {
    disableTelemetry: true
  }
);

You should also set disableTelemetry when triggering workflow runs via client.trigger() to fully disable telemetry