Workflow Context
A workflow’s context is a JavaScript object provided by the serve function and is used to define your workflow endpoint. This context object offers utility methods for creating workflow steps, managing delays, and performing timeout-resistant HTTP calls.
This context object provides utility methods to create workflow steps, wait for certain periods of time or perform timeout-resistant HTTP calls.
Further, the context object provides all request headers, the incoming request payload and current workflow ID.
Context Object Properties
-
qstashClient
: QStash client used by the serve method -
workflowRunId
: Current workflow run ID -
url
: Publically accessible workflow endpoint URL -
failureUrl
: URL for workflow failure notifications. -
requestPayload
: Incoming request payload -
rawInitialPayload
: String version of the initial payload -
headers
: Request headers -
env
: Environment variables
Core Workflow Methods
context.run
Defines and executes a workflow step.
context.sleep
Pauses workflow execution for a specified duration.
Always await
a sleep
action to properly pause execution.
context.sleepUntil
Pauses workflow execution until a specific timestamp.
Always await a sleepUntil
action to properly pause execution.
context.call
Performs an HTTP call as a workflow step, allowing for longer response times.
Can take up to 15 minutes or 2 hours, depending on your QStash plans max HTTP connection timeout.
If the endpoint you request does not return a success response (status code 200-299),
context.call
will still be treated as successful, and the workflow will continue executing.
As a result, failureFunction
or failureUrl
will not be invoked.
To handle non-success cases, you can check the status
field in the response and implement custom logic as needed.
context.call parameters are:
url
: The URL to send the HTTP request to.method
: The HTTP method to use for the request (e.g., GET, POST, PUT, etc.). Defaults to GET.body
: Body to use in the requestheaders
: An object representing the HTTP headers to include in the request.retries
: The number of retry attempts to make if the request fails. Retries use exponential backoff. Defaults to 0 (no retries).timeout
: The maximum duration to wait for a response from the endpoint, in seconds. If retries are enabled, this timeout applies individually to each retry attempt.
context.call attempts to parse the response body as JSON. If this is not possible, the body is returned as it is.
In TypeScript, you can declare the expected result type as follows:
The context.call method can make requests to any public API endpoint. However, it cannot:
- Make requests to localhost (unless you set up a local tunnel, here’s how)
- Make requests to internal Upstash QStash endpoints
context.waitForEvent
Stops the workflow run until it is notified externally to continue.
There is also a timeout setting which makes the workflow continue if it’s not notified within the time frame.
Default timeout value is 7 days.
A workflow run waiting for event can be notified in two ways:
context.notify
: Notify step explained belowclient.notify
: Notify method of the Workflow Client.
context.notify
Notifies workflows waiting for an event with some payload.
notifyResponse
is a list of NotifyResponse
objects:
More details about the Waiter
object:
context.cancel
The methods we listed so far were all for defining a workflow step. context.cancel
is different.
context.cancel
allows you to cancel the current workflow:
Error handling and retries
- context.run automatically retries on failures. Default is 3 retries with exponential backoff.
- context.call doesn’t retry by default. If you wish to add retry, you can use
retries
option. - Future releases will allow more configuration of retry behavior.
Limitations and Plan-Specific-Features
- Sleep durations and HTTP timeouts vary based on your QStash plan.
- See your plan’s “Max Delay” and “Max HTTP Connection Timeout” for specific limits.
Was this page helpful?