Skip to main content
Live. This area is documented as current, user-reliable behavior.

​
Goal

Understand when to move backend work into Durable Jobs and what StackShift guarantees after a job starts.

​
Prerequisites

  • A StackShift API key
  • Node.js or another backend runtime that can expose an HTTP handler

​
Workflow

1
Define a job handler in code.
2
Start the work once with an idempotency key.
3
Break longer work into steps so completed work is remembered.
4
Pause for external events when the flow needs user, webhook, or payment confirmation.
5
Use the run timeline, logs, attempts, and status to inspect what happened.

​
What Durable Jobs is

StackShift Durable Jobs is a reliable execution engine for backend work. It runs jobs outside the request path and keeps enough durable state to retry, resume, and finish safely. Use it for work that should not disappear when a request times out, a process restarts, or an external system is slow. Start the work once. StackShift makes sure it completes safely.

​
Short example

Start a job from an API route, webhook, or backend service. StackShift stores the run and invokes your handler. 
import { StackShift } from '@stackshift-cloud/jobs'

const stackshift = new StackShift({
  apiKey: process.env.STACKSHIFT_API_KEY!,
})

await stackshift.start('send-verification-email',
  { userId: 'user_123', email: 'ada@example.com' },
  {
    queueName: 'emails',
    idempotencyKey: 'verify:user_123',
    idempotencyTtl: '30d',
  }
)

​
Mental model

  • Jobs execute work.
  • Steps break work into durable units.
  • State remembers progress across retries and resumes.
  • Events let a job pause without running compute, then resume when the right signal arrives.
  • Idempotency keys make duplicate starts safe.

​
Expected result

You can explain Durable Jobs as one product concept: jobs execute work, steps divide it, state remembers progress, and events resume paused runs.

Quick Start

Install the SDK, initialize a client, enqueue a job, add a worker handler, and inspect the run.

Idempotency

Use idempotency keys so duplicate requests do not create duplicate work.

Event Waiting + Correlation

Pause a workflow until the right external event arrives, then resume the correct run.