---
name: upstash-qstash
description: "Upstash QStash workflow skill. Use this skill when the user needs Upstash QStash expert for serverless message queues, scheduled and the operator should preserve the upstream workflow, copied support files, and provenance before merging or handing off."
version: "0.0.1"
category: backend
tags: ["upstash-qstash", "upstash", "qstash", "expert", "for", "serverless", "message", "queues"]
complexity: advanced
risk: caution
tools: ["codex-cli", "claude-code", "cursor", "gemini-cli", "opencode"]
source: community
author: "sickn33"
date_added: "2026-04-15"
date_updated: "2026-04-25"
---

# Upstash QStash

## Overview

This public intake copy packages `plugins/antigravity-awesome-skills-claude/skills/upstash-qstash` from `https://github.com/sickn33/antigravity-awesome-skills` into the native Omni Skills editorial shape without hiding its origin.

Use it when the operator needs the upstream workflow, support files, and repository context to stay intact while the public validator and private enhancer continue their normal downstream flow.

This intake keeps the copied upstream files intact and uses the `external_source` block in `metadata.json` plus `ORIGIN.md` as the provenance anchor for review.

# Upstash QStash Upstash QStash expert for serverless message queues, scheduled jobs, and reliable HTTP-based task delivery without managing infrastructure.

Imported source sections that did not map cleanly to the public headings are still preserved below or in the support files. Notable imported sections: Capabilities, Scope, Tooling, Patterns, Sharp Edges, Validation Checks.

## When to Use This Skill

Use this section as the trigger filter. It should make the activation boundary explicit before the operator loads files, runs commands, or opens a pull request.

- User mentions or implies: qstash
- User mentions or implies: upstash queue
- User mentions or implies: serverless cron
- User mentions or implies: scheduled http
- User mentions or implies: message queue serverless
- User mentions or implies: vercel cron

## Operating Table

| Situation | Start here | Why it matters |
| --- | --- | --- |
| First-time use | `metadata.json` | Confirms repository, branch, commit, and imported path through the `external_source` block before touching the copied workflow |
| Provenance review | `ORIGIN.md` | Gives reviewers a plain-language audit trail for the imported source |
| Workflow execution | `SKILL.md` | Starts with the smallest copied file that materially changes execution |
| Supporting context | `SKILL.md` | Adds the next most relevant copied source file without loading the entire package |
| Handoff decision | `## Related Skills` | Helps the operator switch to a stronger native skill when the task drifts |

## Workflow

This workflow is intentionally editorial and operational at the same time. It keeps the imported source useful to the operator while still satisfying the public intake standards that feed the downstream enhancer flow.

1. Confirm the user goal, the scope of the imported workflow, and whether this skill is still the right router for the task.
2. Read the overview and provenance files before loading any copied upstream support files.
3. Load only the references, examples, prompts, or scripts that materially change the outcome for the current request.
4. Execute the upstream workflow while keeping provenance and source boundaries explicit in the working notes.
5. Validate the result against the upstream expectations and the evidence you can point to in the copied files.
6. Escalate or hand off to a related skill when the work moves out of this imported workflow's center of gravity.
7. Before merge or closure, record what was used, what changed, and what the reviewer still needs to verify.

### Imported Workflow Notes

#### Imported: Capabilities

- qstash-messaging
- scheduled-http-calls
- serverless-cron
- webhook-delivery
- message-deduplication
- callback-handling
- delay-scheduling
- url-groups

## Examples

### Example 1: Ask for the upstream workflow directly

```text
Use @upstash-qstash to handle <task>. Start from the copied upstream workflow, load only the files that change the outcome, and keep provenance visible in the answer.
```

**Explanation:** This is the safest starting point when the operator needs the imported workflow, but not the entire repository.

### Example 2: Ask for a provenance-grounded review

```text
Review @upstash-qstash against metadata.json and ORIGIN.md, then explain which copied upstream files you would load first and why.
```

**Explanation:** Use this before review or troubleshooting when you need a precise, auditable explanation of origin and file selection.

### Example 3: Narrow the copied support files before execution

```text
Use @upstash-qstash for <task>. Load only the copied references, examples, or scripts that change the outcome, and name the files explicitly before proceeding.
```

**Explanation:** This keeps the skill aligned with progressive disclosure instead of loading the whole copied package by default.

### Example 4: Build a reviewer packet

```text
Review @upstash-qstash using the copied upstream files plus provenance, then summarize any gaps before merge.
```

**Explanation:** This is useful when the PR is waiting for human review and you want a repeatable audit packet.



## Best Practices

Treat the generated public skill as a reviewable packaging layer around the upstream repository. The goal is to keep provenance explicit and load only the copied source material that materially improves execution.

- HTTP is the interface - if it speaks HTTPS, it speaks QStash
- Endpoints must be public - QStash calls your URLs from the cloud
- Verify signatures always - never trust unverified webhooks
- Schedules are fire-and-forget - QStash handles the cron
- Retries are built-in - but configure them for your use case
- Delays are free - schedule seconds to days in the future
- Callbacks complete the loop - know when delivery succeeds or fails

### Imported Operating Notes

#### Imported: Principles

- HTTP is the interface - if it speaks HTTPS, it speaks QStash
- Endpoints must be public - QStash calls your URLs from the cloud
- Verify signatures always - never trust unverified webhooks
- Schedules are fire-and-forget - QStash handles the cron
- Retries are built-in - but configure them for your use case
- Delays are free - schedule seconds to days in the future
- Callbacks complete the loop - know when delivery succeeds or fails
- Deduplication prevents double-processing - use message IDs

## Troubleshooting

### Problem: The operator skipped the imported context and answered too generically

**Symptoms:** The result ignores the upstream workflow in `plugins/antigravity-awesome-skills-claude/skills/upstash-qstash`, fails to mention provenance, or does not use any copied source files at all.
**Solution:** Re-open `metadata.json`, `ORIGIN.md`, and the most relevant copied upstream files. Check the `external_source` block first, then restate the provenance before continuing.

### Problem: The imported workflow feels incomplete during review

**Symptoms:** Reviewers can see the generated `SKILL.md`, but they cannot quickly tell which references, examples, or scripts matter for the current task.
**Solution:** Point at the exact copied references, examples, scripts, or assets that justify the path you took. If the gap is still real, record it in the PR instead of hiding it.

### Problem: The task drifted into a different specialization

**Symptoms:** The imported skill starts in the right place, but the work turns into debugging, architecture, design, security, or release orchestration that a native skill handles better.
**Solution:** Use the related skills section to hand off deliberately. Keep the imported provenance visible so the next skill inherits the right context instead of starting blind.



## Related Skills

- `@00-andruia-consultant` - Use when the work is better handled by that native specialization after this imported skill establishes context.
- `@00-andruia-consultant-v2` - Use when the work is better handled by that native specialization after this imported skill establishes context.
- `@10-andruia-skill-smith` - Use when the work is better handled by that native specialization after this imported skill establishes context.
- `@10-andruia-skill-smith-v2` - Use when the work is better handled by that native specialization after this imported skill establishes context.

## Additional Resources

Use this support matrix and the linked files below as the operator packet for this imported skill. They should reflect real copied source material, not generic scaffolding.

| Resource family | What it gives the reviewer | Example path |
| --- | --- | --- |
| `references` | copied reference notes, guides, or background material from upstream | `references/n/a` |
| `examples` | worked examples or reusable prompts copied from upstream | `examples/n/a` |
| `scripts` | upstream helper scripts that change execution or validation | `scripts/n/a` |
| `agents` | routing or delegation notes that are genuinely part of the imported package | `agents/n/a` |
| `assets` | supporting assets or schemas copied from the source package | `assets/n/a` |



### Imported Reference Notes

#### Imported: Scope

- complex-workflows -> inngest
- redis-queues -> bullmq-specialist
- event-sourcing -> event-architect
- workflow-orchestration -> temporal-craftsman

#### Imported: Tooling

### Core

- qstash-sdk
- upstash-console

### Frameworks

- nextjs
- cloudflare-workers
- vercel-functions
- aws-lambda
- netlify-functions

### Patterns

- scheduled-jobs
- delayed-messages
- webhook-fanout
- callback-verification

### Related

- upstash-redis
- upstash-kafka

#### Imported: Patterns

### Basic Message Publishing

Sending messages to be delivered to endpoints

**When to use**: Need reliable async HTTP calls

import { Client } from '@upstash/qstash';

const qstash = new Client({
  token: process.env.QSTASH_TOKEN!,
});

// Simple message to endpoint
await qstash.publishJSON({
  url: 'https://myapp.com/api/process',
  body: {
    userId: '123',
    action: 'welcome-email',
  },
});

// With delay (process in 1 hour)
await qstash.publishJSON({
  url: 'https://myapp.com/api/reminder',
  body: { userId: '123' },
  delay: 60 * 60,  // seconds
});

// With specific delivery time
await qstash.publishJSON({
  url: 'https://myapp.com/api/scheduled',
  body: { report: 'daily' },
  notBefore: Math.floor(Date.now() / 1000) + 86400,  // tomorrow
});

### Scheduled Cron Jobs

Setting up recurring scheduled tasks

**When to use**: Need periodic background jobs without infrastructure

import { Client } from '@upstash/qstash';

const qstash = new Client({
  token: process.env.QSTASH_TOKEN!,
});

// Create a scheduled job
const schedule = await qstash.schedules.create({
  destination: 'https://myapp.com/api/cron/daily-report',
  cron: '0 9 * * *',  // Every day at 9 AM UTC
  body: JSON.stringify({ type: 'daily' }),
  headers: {
    'Content-Type': 'application/json',
  },
});

console.log('Schedule created:', schedule.scheduleId);

// List all schedules
const schedules = await qstash.schedules.list();

// Delete a schedule
await qstash.schedules.delete(schedule.scheduleId);

### Signature Verification

Verifying QStash message signatures in your endpoint

**When to use**: Any endpoint receiving QStash messages (always!)

// app/api/webhook/route.ts (Next.js App Router)
import { Receiver } from '@upstash/qstash';
import { NextRequest, NextResponse } from 'next/server';

const receiver = new Receiver({
  currentSigningKey: process.env.QSTASH_CURRENT_SIGNING_KEY!,
  nextSigningKey: process.env.QSTASH_NEXT_SIGNING_KEY!,
});

export async function POST(req: NextRequest) {
  const signature = req.headers.get('upstash-signature');
  const body = await req.text();

  // ALWAYS verify signature
  const isValid = await receiver.verify({
    signature: signature!,
    body,
    url: req.url,
  });

  if (!isValid) {
    return NextResponse.json(
      { error: 'Invalid signature' },
      { status: 401 }
    );
  }

  // Safe to process
  const data = JSON.parse(body);
  await processMessage(data);

  return NextResponse.json({ success: true });
}

### Callback for Delivery Status

Getting notified when messages are delivered or fail

**When to use**: Need to track delivery status for critical messages

import { Client } from '@upstash/qstash';

const qstash = new Client({
  token: process.env.QSTASH_TOKEN!,
});

// Publish with callback
await qstash.publishJSON({
  url: 'https://myapp.com/api/critical-task',
  body: { taskId: '456' },
  callback: 'https://myapp.com/api/qstash-callback',
  failureCallback: 'https://myapp.com/api/qstash-failed',
});

// Callback endpoint receives delivery status
// app/api/qstash-callback/route.ts
export async function POST(req: NextRequest) {
  // Verify signature first!
  const data = await req.json();

  // data contains:
  // - sourceMessageId: original message ID
  // - url: destination URL
  // - status: HTTP status code
  // - body: response body

  if (data.status >= 200 && data.status < 300) {
    await markTaskComplete(data.sourceMessageId);
  }

  return NextResponse.json({ received: true });
}

### URL Groups (Fan-out)

Sending messages to multiple endpoints at once

**When to use**: Need to notify multiple services about an event

import { Client } from '@upstash/qstash';

const qstash = new Client({
  token: process.env.QSTASH_TOKEN!,
});

// Create a URL group
await qstash.urlGroups.addEndpoints({
  name: 'order-processors',
  endpoints: [
    { url: 'https://inventory.myapp.com/api/process' },
    { url: 'https://shipping.myapp.com/api/process' },
    { url: 'https://analytics.myapp.com/api/track' },
  ],
});

// Publish to the group - all endpoints receive the message
await qstash.publishJSON({
  urlGroup: 'order-processors',
  body: {
    orderId: '789',
    event: 'order.placed',
  },
});

### Message Deduplication

Preventing duplicate message processing

**When to use**: Idempotency is critical (payments, notifications)

import { Client } from '@upstash/qstash';

const qstash = new Client({
  token: process.env.QSTASH_TOKEN!,
});

// Deduplicate by custom ID (within deduplication window)
await qstash.publishJSON({
  url: 'https://myapp.com/api/charge',
  body: { orderId: '123', amount: 5000 },
  deduplicationId: 'charge-order-123',  // Won't send again within window
});

// Content-based deduplication
await qstash.publishJSON({
  url: 'https://myapp.com/api/notify',
  body: { userId: '456', message: 'Hello' },
  contentBasedDeduplication: true,  // Hash of body used as ID
});

#### Imported: Sharp Edges

### Not verifying QStash webhook signatures

Severity: CRITICAL

Situation: Endpoint accepts any POST request. Attacker discovers your callback URL.
Fake messages flood your system. Malicious payloads processed as trusted.

Symptoms:
- No Receiver import in webhook handler
- Missing upstash-signature header check
- Processing request before verification

Why this breaks:
QStash endpoints are public URLs. Without signature verification, anyone
can send requests. This is a direct path to unauthorized message processing
and potential data manipulation.

Recommended fix:

# Always verify signatures with both keys:
```typescript
import { Receiver } from '@upstash/qstash';

const receiver = new Receiver({
  currentSigningKey: process.env.QSTASH_CURRENT_SIGNING_KEY!,
  nextSigningKey: process.env.QSTASH_NEXT_SIGNING_KEY!,
});

export async function POST(req: NextRequest) {
  const signature = req.headers.get('upstash-signature');
  const body = await req.text();  // Raw body required

  const isValid = await receiver.verify({
    signature: signature!,
    body,
    url: req.url,
  });

  if (!isValid) {
    return NextResponse.json({ error: 'Invalid signature' }, { status: 401 });
  }

  // Safe to process
}
```

# Why two keys?
- QStash rotates signing keys
- nextSigningKey becomes current during rotation
- Both must be checked for seamless key rotation

### Callback endpoint taking too long to respond

Severity: HIGH

Situation: Webhook handler does heavy processing. Takes 30+ seconds. QStash times out.
Marks message as failed. Retries. Double processing begins.

Symptoms:
- Webhook timeouts in QStash dashboard
- Messages marked failed then retried
- Duplicate processing of same message

Why this breaks:
QStash has a 30-second timeout for callbacks. If your endpoint doesn't respond
in time, QStash considers it failed and retries. Long-running handlers create
duplicate message processing and wasted retries.

Recommended fix:

# Design for fast acknowledgment:
```typescript
export async function POST(req: NextRequest) {
  // 1. Verify signature first (fast)
  // 2. Parse and validate message (fast)
  // 3. Queue for async processing (fast)

  const message = await parseMessage(req);

  // Don't do this:
  // await processHeavyWork(message);  // Could timeout!

  // Do this instead:
  await db.jobs.create({ data: message, status: 'pending' });
  // Or use another QStash message for the heavy work

  return NextResponse.json({ queued: true });  // Respond fast
}
```

# Alternative: Use QStash for the heavy work
```typescript
// Webhook receives trigger
await qstash.publishJSON({
  url: 'https://myapp.com/api/heavy-process',
  body: { jobId: message.id },
});
return NextResponse.json({ delegated: true });
```

# For Vercel: Consider using Edge runtime for faster cold starts

### Hitting QStash rate limits unexpectedly

Severity: HIGH

Situation: Burst of events triggers mass message publishing. QStash rate limit hit.
Messages rejected. Users don't get notifications. Critical tasks delayed.

Symptoms:
- 429 errors from QStash
- Messages not being delivered
- Sudden drop in processing during peak times

Why this breaks:
QStash has plan-based rate limits. Free tier: 500 messages/day. Pro: higher
but still limited. Bursts can exhaust limits quickly. Without monitoring,
you won't know until users complain.

Recommended fix:

# Check your plan limits:
- Free: 500 messages/day
- Pay as you go: Check dashboard
- Pro: Higher limits, check dashboard

# Implement rate limit handling:
```typescript
try {
  await qstash.publishJSON({ url, body });
} catch (error) {
  if (error.message?.includes('rate limit')) {
    // Queue locally and retry later
    await localQueue.add('qstash-retry', { url, body });
  }
  throw error;
}
```

# Batch messages when possible:
```typescript
// Instead of 100 individual publishes
await qstash.batchJSON({
  messages: items.map(item => ({
    url: 'https://myapp.com/api/process',
    body: { itemId: item.id },
  })),
});
```

# Monitor in dashboard:
Upstash Console shows usage and limits

### Not using deduplication for critical operations

Severity: HIGH

Situation: Network hiccup during publish. SDK retries. Same message sent twice.
Customer charged twice. Email sent twice. Data corrupted.

Symptoms:
- Duplicate charges or emails
- Double processing of same event
- User complaints about duplicates

Why this breaks:
Network failures and retries happen. Without deduplication, the same logical
message can be sent multiple times. QStash provides deduplication, but you
must use it for critical operations.

Recommended fix:

# Use deduplication for critical messages:
```typescript
// Custom ID (best for business operations)
await qstash.publishJSON({
  url: 'https://myapp.com/api/charge',
  body: { orderId: '123', amount: 5000 },
  deduplicationId: `charge-${orderId}`,  // Same ID = same message
});

// Content-based (good for notifications)
await qstash.publishJSON({
  url: 'https://myapp.com/api/notify',
  body: { userId: '456', type: 'welcome' },
  contentBasedDeduplication: true,  // Hash of body
});
```

# Deduplication window:
- Default: 60 seconds
- Messages with same ID in window are deduplicated
- Plan for this in your retry logic

# Also make endpoints idempotent:
Check if operation already completed before processing

### Expecting QStash to reach private/localhost endpoints

Severity: CRITICAL

Situation: Development works with local server. Deploy to production with internal URL.
QStash can't reach it. All messages fail silently. No processing happens.

Symptoms:
- Messages show "failed" in QStash dashboard
- Works locally but fails in "production"
- Using http:// instead of https://

Why this breaks:
QStash runs in Upstash's cloud. It can only reach public, internet-accessible
URLs. localhost, internal IPs, and private networks are unreachable. This is
a fundamental architecture requirement, not a configuration issue.

Recommended fix:

# Production requirements:
- URL must be publicly accessible
- HTTPS required (HTTP will fail)
- No localhost, 127.0.0.1, or private IPs

# Local development options:

# Option 1: ngrok/localtunnel
```bash
ngrok http 3000
# Use the ngrok URL for QStash testing
```

# Option 2: QStash local development mode
```typescript
// In development, skip QStash and call directly
if (process.env.NODE_ENV === 'development') {
  await fetch('http://localhost:3000/api/process', {
    method: 'POST',
    body: JSON.stringify(data),
  });
} else {
  await qstash.publishJSON({ url, body: data });
}
```

# Option 3: Use Vercel preview URLs
Preview deploys give you public URLs for testing

### Using default retry behavior for all message types

Severity: MEDIUM

Situation: Critical payment webhook uses defaults. 3 retries over minutes. Payment
processor is temporarily down for 15 minutes. Message marked as failed.
Payment reconciliation manual work required.

Symptoms:
- Critical messages marked failed
- Manual intervention needed for retries
- Temporary outages causing permanent failures

Why this breaks:
Default retry behavior (3 attempts, short backoff) works for many cases but
not all. Some endpoints need more attempts, longer backoff, or different
strategies. One size doesn't fit all.

Recommended fix:

# Configure retries per message:
```typescript
// Critical operations: more retries, longer backoff
await qstash.publishJSON({
  url: 'https://myapp.com/api/payment-webhook',
  body: { paymentId: '123' },
  retries: 5,
  // Backoff: 10s, 30s, 1m, 5m, 30m
});

// Non-critical notifications: fewer retries
await qstash.publishJSON({
  url: 'https://myapp.com/api/analytics',
  body: { event: 'pageview' },
  retries: 1,  // Fail fast, not critical
});
```

# Consider your endpoint's recovery time:
- Database down: May need 5+ minutes
- Third-party API: May need hours
- Internal service: Usually quick

# Use failure callbacks for dead letter handling:
```typescript
await qstash.publishJSON({
  url: 'https://myapp.com/api/critical',
  body: data,
  failureCallback: 'https://myapp.com/api/dead-letter',
});
```

### Sending large payloads instead of references

Severity: MEDIUM

Situation: Message contains entire document (5MB). QStash rejects - body too large.
Even if accepted, slow to transmit. Expensive. Wastes bandwidth.

Symptoms:
- Message publish failures
- Slow message delivery
- High bandwidth costs

Why this breaks:
QStash has message size limits (around 500KB body). Large payloads slow
delivery, increase costs, and can fail entirely. Messages should be
lightweight triggers, not data carriers.

Recommended fix:

# Send references, not data:
```typescript
// BAD: Large payload
await qstash.publishJSON({
  url: 'https://myapp.com/api/process',
  body: { document: largeDocumentContent },  // 5MB!
});

// GOOD: Reference only
await qstash.publishJSON({
  url: 'https://myapp.com/api/process',
  body: { documentId: 'doc_123' },  // Fetch in handler
});
```

# In your handler:
```typescript
export async function POST(req: NextRequest) {
  const { documentId } = await req.json();
  const document = await storage.get(documentId);  // Fetch actual data
  await processDocument(document);
}
```

# Large data storage options:
- S3/R2/Blob storage for files
- Database for structured data
- Redis for temporary data (Upstash Redis pairs well)

### Not using callback/failureCallback for critical flows

Severity: MEDIUM

Situation: Important task published. QStash delivers. Endpoint processes. But your
system doesn't know it succeeded. User stuck waiting. No feedback loop.

Symptoms:
- No visibility into message delivery
- Users waiting for actions that completed
- No alerting on failures

Why this breaks:
QStash is fire-and-forget by default. Without callbacks, you don't know
if messages were delivered successfully. For critical flows, you need
the feedback loop to update state and handle failures.

Recommended fix:

# Use callbacks for critical operations:
```typescript
await qstash.publishJSON({
  url: 'https://myapp.com/api/send-email',
  body: { userId: '123', template: 'welcome' },
  callback: 'https://myapp.com/api/email-callback',
  failureCallback: 'https://myapp.com/api/email-failed',
});
```

# Handle the callback:
```typescript
// app/api/email-callback/route.ts
export async function POST(req: NextRequest) {
  // Verify signature first!
  const data = await req.json();

  // data.sourceMessageId - original message
  // data.status - HTTP status code
  // data.body - response from endpoint

  await db.emailLogs.update({
    where: { messageId: data.sourceMessageId },
    data: { status: 'delivered' },
  });

  return NextResponse.json({ received: true });
}
```

# Failure callback for alerting:
```typescript
// app/api/email-failed/route.ts
export async function POST(req: NextRequest) {
  const data = await req.json();
  await alerting.notify(`Email failed: ${data.sourceMessageId}`);
  await db.emailLogs.update({
    where: { messageId: data.sourceMessageId },
    data: { status: 'failed', error: data.body },
  });
}
```

### Cron schedules using wrong timezone

Severity: MEDIUM

Situation: Scheduled daily report at "9am". But 9am in which timezone? QStash uses UTC.
Report runs at 4am local time. Users confused. Support tickets filed.

Symptoms:
- Schedules running at unexpected times
- Off-by-one-hour issues during DST
- User complaints about report timing

Why this breaks:
QStash cron schedules run in UTC. If you think in local time but configure
in UTC, schedules will run at unexpected times. This is especially tricky
with daylight saving time changes.

Recommended fix:

# QStash uses UTC:
```typescript
// This runs at 9am UTC, not local time
await qstash.schedules.create({
  destination: 'https://myapp.com/api/daily-report',
  cron: '0 9 * * *',  // 9am UTC
});
```

# Convert to UTC:
- 9am EST = 2pm UTC (winter) / 1pm UTC (summer)
- 9am PST = 5pm UTC (winter) / 4pm UTC (summer)

# Document timezone in schedule name:
```typescript
await qstash.schedules.create({
  destination: 'https://myapp.com/api/daily-report',
  cron: '0 14 * * *',  // 9am EST (14:00 UTC)
  body: JSON.stringify({
    timezone: 'America/New_York',
    localTime: '9:00 AM',
  }),
});
```

# Handle DST programmatically if needed:
Update schedules when DST changes, or accept UTC timing

### URL groups with dead or outdated endpoints

Severity: MEDIUM

Situation: URL group has 5 endpoints. One service deprecated months ago. Messages
still fan out to it. Failures in dashboard. Wasted attempts. Slower delivery.

Symptoms:
- Failed deliveries in URL groups
- Messages to deprecated services
- Slow fan-out due to timeouts

Why this breaks:
URL groups persist until explicitly updated. When services change, endpoints
become stale. QStash tries to deliver to dead URLs, wastes retries, and
the failure noise obscures real issues.

Recommended fix:

# Audit URL groups regularly:
```typescript
const groups = await qstash.urlGroups.list();
for (const group of groups) {
  console.log(`Group: ${group.name}`);
  for (const endpoint of group.endpoints) {
    // Check if endpoint is still valid
    try {
      await fetch(endpoint.url, { method: 'HEAD' });
      console.log(`  OK: ${endpoint.url}`);
    } catch {
      console.log(`  DEAD: ${endpoint.url}`);
    }
  }
}
```

# Update groups when services change:
```typescript
// Remove dead endpoint
await qstash.urlGroups.removeEndpoints({
  name: 'order-processors',
  endpoints: [{ url: 'https://old-service.myapp.com/api/process' }],
});
```

# Automate in CI/CD:
Check URL group health as part of deployment

#### Imported: Validation Checks

### Webhook signature verification

Severity: CRITICAL

Message: QStash webhook handlers must verify signatures using Receiver

Fix action: Add signature verification: const receiver = new Receiver({ currentSigningKey, nextSigningKey }); await receiver.verify({ signature, body, url })

### Both signing keys configured

Severity: CRITICAL

Message: QStash Receiver must have both currentSigningKey and nextSigningKey for key rotation

Fix action: Configure both keys: new Receiver({ currentSigningKey: process.env.QSTASH_CURRENT_SIGNING_KEY, nextSigningKey: process.env.QSTASH_NEXT_SIGNING_KEY })

### QStash token hardcoded

Severity: CRITICAL

Message: QStash token must not be hardcoded - use environment variables

Fix action: Use process.env.QSTASH_TOKEN

### QStash signing keys hardcoded

Severity: CRITICAL

Message: QStash signing keys must not be hardcoded

Fix action: Use process.env.QSTASH_CURRENT_SIGNING_KEY and process.env.QSTASH_NEXT_SIGNING_KEY

### Localhost URL in QStash publish

Severity: CRITICAL

Message: QStash cannot reach localhost - endpoints must be publicly accessible

Fix action: Use a public URL (e.g., your deployed domain or ngrok for testing)

### HTTP URL instead of HTTPS

Severity: ERROR

Message: QStash requires HTTPS URLs for security

Fix action: Change http:// to https://

### QStash publish without error handling

Severity: ERROR

Message: QStash publish calls should have error handling for rate limits and failures

Fix action: Wrap in try/catch and handle errors appropriately

### Using parsed JSON for signature verification

Severity: CRITICAL

Message: Signature verification requires raw body (req.text()), not parsed JSON

Fix action: Use await req.text() to get raw body for verification

### Callback endpoint without signature verification

Severity: CRITICAL

Message: Callback endpoints must also verify signatures - they receive QStash requests too

Fix action: Add Receiver signature verification to callback handlers

### Schedule without destination URL

Severity: ERROR

Message: QStash schedules require a destination URL

Fix action: Add destination: 'https://your-app.com/api/endpoint' to schedule options

#### Imported: Collaboration

### Delegation Triggers

- complex workflow|multi-step|state machine -> inngest (Need durable step functions with checkpointing)
- redis queue|worker process|job priority -> bullmq-specialist (Need traditional queue with workers)
- ai background|long running ai|model inference -> trigger-dev (Need AI-specific background processing)
- deploy|vercel|production|environment -> vercel-deployment (Need deployment configuration for QStash)
- database|persistence|state|sync -> supabase-backend (Need database for job state)
- auth|user context|session -> nextjs-supabase-auth (Need user context in message handlers)

### Serverless Background Jobs

Skills: upstash-qstash, nextjs-app-router, vercel-deployment

Workflow:

```
1. Define API route handlers (nextjs-app-router)
2. Configure QStash integration (upstash-qstash)
3. Deploy with environment vars (vercel-deployment)
```

### Reliable Webhooks

Skills: upstash-qstash, stripe-integration, supabase-backend

Workflow:

```
1. Receive webhooks from Stripe (stripe-integration)
2. Queue for reliable processing (upstash-qstash)
3. Persist state to database (supabase-backend)
```

### Scheduled Reports

Skills: upstash-qstash, email-systems, supabase-backend

Workflow:

```
1. Configure cron schedule (upstash-qstash)
2. Query data for report (supabase-backend)
3. Send via email system (email-systems)
```

### Fan-out Notifications

Skills: upstash-qstash, email-systems, slack-bot-builder

Workflow:

```
1. Publish to URL group (upstash-qstash)
2. Email handler receives (email-systems)
3. Slack handler receives (slack-bot-builder)
```

### Gradual Migration to Workflows

Skills: upstash-qstash, inngest

Workflow:

```
1. Start with simple QStash messages (upstash-qstash)
2. Identify multi-step patterns
3. Migrate complex flows to Inngest (inngest)
4. Keep simple schedules in QStash
```

#### Imported: Limitations

- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.