Skip to main content

​
Overview

QStash is available in two regions: EU region and US region. Each region is completely independent with its own infrastructure, pricing, resources, logs, and messages.

​
Regional URLs

  • EU Region: https://qstash-eu-central-1.upstash.io, or https://qstash.upstash.io
  • US Region: https://qstash-us-east-1.upstash.io

​
Key Concepts

​
Separate Regions

Each QStash region maintains:
  • Separate pricing and billing: Usage in each region is tracked and billed independently
  • Separate resources: Messages, queues, schedules, URL groups and DLQ are region-specific
  • Separate credentials: Each region has its own API tokens and signing keys

​
Migration Between Regions

If you don’t have any active resources (active messages, schedules, url groups etc), you can simply update your environment variables with the new region to migrate. If you have active resources, you will need to migrate more gracefully, as described below. You can migrate your QStash resources from one region to another using the Upstash Console:
  1. Navigate to the QStash tab on Upstash Console
  2. Click the Migrate button
  3. Follow the guided migration process
The migration tool will:
  • Help you set up multi-region environment variables
  • Copy and update your QStash resources (schedules, url groups, queues)
Your message logs or DLQ aren’t part of the migration. They will remain in the old region.
After migration, your app will be able to handle requests from both regions simultaneously to ensure a smooth transition.

​
Operating Modes

QStash SDK supports two modes of operation:

​
Single-Region Mode (Default)

When QSTASH_REGION environment variable is not set, the SDK operates in single-region mode:
  • Uses QSTASH_TOKEN and QSTASH_URL (or defaults to EU region)
  • All outgoing messages are sent through the configured region
  • Incoming messages are verified using default signing keys if signing keys are defined
# Single-region configuration (EU)
QSTASH_URL="https://qstash.upstash.io"
QSTASH_TOKEN="your_eu_token"
QSTASH_CURRENT_SIGNING_KEY="your_eu_current_key"
QSTASH_NEXT_SIGNING_KEY="your_eu_next_key"

​
Multi-Region Mode

When QSTASH_REGION is set to US_EAST_1 or EU_CENTRAL_1, the SDK enables multi-region mode:
  • Uses region-specific credentials (e.g., US_EAST_1_QSTASH_TOKEN)
  • Automatically handles region detection for incoming requests
  • Supports receiving messages from multiple regions simultaneously
# Multi-region configuration with US as primary
QSTASH_REGION="US_EAST_1"

US_EAST_1_QSTASH_URL="https://qstash-us-east-1.upstash.io"
US_EAST_1_QSTASH_TOKEN="your_us_token"
US_EAST_1_QSTASH_CURRENT_SIGNING_KEY="your_us_current_key"
US_EAST_1_QSTASH_NEXT_SIGNING_KEY="your_us_next_key"

EU_CENTRAL_1_QSTASH_URL="https://qstash-eu-central-1.upstash.io"
EU_CENTRAL_1_QSTASH_TOKEN="your_eu_token"
EU_CENTRAL_1_QSTASH_CURRENT_SIGNING_KEY="your_eu_current_key"
EU_CENTRAL_1_QSTASH_NEXT_SIGNING_KEY="your_eu_next_key"
Multi-region mode relies on environment variables being available via process.env. It won’t work on platforms where process.env is not available, such as Cloudflare Workers.

​
SDK Requirements

Multi-region support requires:
  • @upstash/qstash >= 2.9.0
Update your dependency: 
npm install @upstash/qstash@latest

​
Outgoing Messages

​
How the SDK Selects a Region

For outgoing messages (publishing messages, managing queues, schedules, etc.), the SDK determines which region to use based on the QSTASH_REGION environment variable: Single-Region Mode (QSTASH_REGION not set):
  1. SDK reads QSTASH_TOKEN and QSTASH_URL
  2. If QSTASH_URL is not set, defaults to EU region
  3. All messages are published through this region
Multi-Region Mode (QSTASH_REGION set):
  1. SDK reads the QSTASH_REGION value (e.g., US_EAST_1)
  2. Uses region-specific credentials: {QSTASH_REGION}_QSTASH_TOKEN and {QSTASH_REGION}_QSTASH_URL
  3. All messages are published through the specified region
  4. Falls back to default credentials if region-specific ones are missing

​
Incoming Messages

​
Understanding the Region Header

QStash includes an upstash-region header with every request to indicate the source region: 
upstash-region: US-EAST-1

​
How the SDK Verifies Incoming Requests

The SDK uses different approaches depending on the operating mode: Single-Region Mode:
  • Uses default signing keys: QSTASH_CURRENT_SIGNING_KEY and QSTASH_NEXT_SIGNING_KEY
  • Ignores the upstash-region header
Multi-Region Mode:
  1. Checks the upstash-region header from the incoming request
  2. Normalizes the region name (e.g., US-EAST-1 → US_EAST_1)
  3. Looks for region-specific signing keys: {REGION}_QSTASH_CURRENT_SIGNING_KEY
  4. Falls back to default signing keys if region-specific ones are missing

​
Example: Verifying Incoming Messages

import { Receiver } from "@upstash/qstash";

// Initialize receiver (works in both modes)
const receiver = new Receiver();

// Verify the incoming request
await receiver.verify({
  signature: request.headers.get("upstash-signature")!,
  body: await request.text(),
  // Pass the region header for multi-region support
  upstashRegion: request.headers.get("upstash-region") ?? undefined,
});

​
Platform-Specific Verification

Most platform verifiers automatically handle the region header: 
// Next.js App Router - automatically handles multi-region
import { verifySignatureAppRouter } from "@upstash/qstash/nextjs";

export const POST = verifySignatureAppRouter(async (req) => {
  const body = await req.json();
  return Response.json({ success: true });
});