Start a Run

You’ve defined your workflow, and the final step is to trigger the endpoint!

There are three main ways to start your workflow:

​

1. Using client.trigger (Recommended)

We recommend using client.trigger to start your workflow as it returns the workflow run ID in its result and results in one less QStash publish per workflow.

// Using the workflow client
import { Client } from "@upstash/workflow";

const client = new Client({ token: "<QSTASH_TOKEN>" });

const { workflowRunId } = await client.trigger({
  url: "https://workflow-endpoint.com",
  body: "hello there!",         // Optional body
  headers: { ... },             // Optional headers
  workflowRunId: "my-workflow", // Optional workflow run ID
  retries: 3                    // Optional retries for the initial request
});

​

2. Publishing a message with QStash

// Using the QStash client
import { Client } from "@upstash/qstash";

const client = new Client({ token: "<QSTASH_TOKEN>" });

const { messageId } = await client.publishJSON({
  url: "https://workflow-endpoint.com",
  body: { hello: "there!" },
  headers: { ... },    
  retries: 3           
});

​

3. Sending an HTTP Request

• curl
• fetch

curl -X POST https://workflow-endpoint.com \
     -H "my-header: foo" \
     -b '{"foo": "bar"}'

​

Secured Endpoints

If you’ve secured your endpoint with signing keys, only the first two methods (trigger and publish) will work. Direct calls to the endpoint (e.g., via curl or fetch) will not be accepted.

​

Accessing Payload and Headers

When you call the endpoint, the payload and headers you send will be accessible in the context:

• The payload is available in the context.requestPayload field.
• The headers are available in the context.headers field.

For more details, refer to the documentation on the Context object.