Durable Jobs overview

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

Define a job handler in code.

Start the work once with an idempotency key.

Break longer work into steps so completed work is remembered.

Pause for external events when the flow needs user, webhook, or payment confirmation.

Use the run timeline, logs, attempts, and status to inspect what happened.

SDK 0.2.0 callback authentication

JavaScript and Go SDK 0.2.0 provide built-in callback verification. JavaScript requires Node.js 20 or newer. Signed callbacks also require the coordinated backend reliability rollout described below. The adapters authenticate raw-body Ed25519 signatures, timestamp freshness, and trusted account/run binding before dispatch, with a 4 MiB body limit. Configure the public key and account ID obtained from the authenticated verification-key endpoint; never trust callback-provided keys or URLs. Saved steps stop on failed or malformed state reads; only HTTP 404 means a missing step. Continuation checkpoints remain separate from events. Go preserves zero counter increments. Execution remains at least once and requires stable downstream idempotency keys. For JavaScript, use handleRequest for public routes. For Go, configure Options.Verification before mounting HTTPHandler; missing configuration or unsigned callbacks return HTTP 401. Low-level invocation methods remain for already authenticated input only.

JavaScript 0.2.0 handler

export async function POST(request: Request) {
  return stackshift.handleRequest(request, {
    publicKey: process.env.STACKSHIFT_JOBS_PUBLIC_KEY!,
    userId: process.env.STACKSHIFT_ACCOUNT_ID!,
  })
}

Go 0.2.0 verification configuration

client, err := stackshift.New(stackshift.Options{
  APIKey: os.Getenv("STACKSHIFT_API_KEY"),
  Verification: &stackshift.InvocationVerification{
    PublicKey: os.Getenv("STACKSHIFT_JOBS_PUBLIC_KEY"),
    UserID: os.Getenv("STACKSHIFT_ACCOUNT_ID"),
  },
})
if err != nil { return err }
// Register jobs before starting the HTTP server.
http.Handle("/stackshift/jobs", client.HTTPHandler())

Reliability update awaiting rollout

The reliability changes below are implemented but not deployed. They require migration 000524 and coordinated API and worker replacement. Existing deployments may still exhibit the earlier behavior. The prepared release guard requires coordinated replacement, refuses partial upgrades or pending legacy work, and verifies a database backup before migration; signing keys persist across deployments. Execution is at least once. Use a stable downstream idempotency key for each side effect, such as runId plus an operation name. A crash after an external effect but before its acknowledgment can repeat it, even when enqueue deduplication and saved steps are enabled.

Customer jobs use a public HTTPS handler URL, supplied on first registration or inherited from an existing customer definition. Accepted runs pin that URL and version; later submissions do not retarget queued work.
Platform job, queue, and event names are reserved. Use the owning platform feature to manage those runs. Customer callbacks have separate execution slots from platform jobs.
A matching event resumes one oldest active waiter. Use different correlation keys or separate events for multiple recipients. Successful waits preserve the retry budget and expose result.event separately from result.checkpoint.
Retry policy: explicit request override, then queue default, then three attempts. HTTP 408, 429 and 5xx are retryable with jitter and bounded Retry-After. Other non-2xx replies, redirects, malformed successful replies, and responses over 4 MiB fail permanently. Empty 2xx replies mean an empty result.
HTTP callbacks have a five-minute limit. Internal handlers have a thirty-minute execution deadline. Three expired-lease recoveries are allowed before a run fails for operator inspection.
Expired idempotency keys, state, and locks are removed in bounded batches. Events older than 90 days are removed only when no wait or unexpired idempotency key references them. Run history and referenced events are retained; no automatic terminal-run deletion is enabled.
Asset workflow creation, durable enqueue, linking, and inbound webhook delivery reservations commit atomically. Failed submissions do not consume the delivery ID.
List failed runs and inspect their logs before manually retrying. Retry and cancellation are recorded in the run log. Platform runs must be managed through their owning feature.

Verify callbacks before executing jobs

After the coordinated rollout, fetch GET /api/v1/jobs/verification-key using your StackShift API key. Configure its data.public_key and data.user_id on your handler. Do not fetch a key from a callback-supplied URL. Keep the private signing seed on StackShift servers only. Older Node SDK 0.1.1 does not authenticate callbacks. For that version, verify the raw body and expected account before calling handleInvocation using the wrapper below. SDK 0.2.0 includes handleRequest and verifyInvocation, so no separate wrapper is required. Deduplicate external side effects using stable business keys; signature verification alone does not prevent retries.

verify-invocation.mjs

import { createPublicKey, verify } from 'node:crypto'

// Configure both values from the authenticated /jobs/verification-key response.
export async function verifyInvocation(request, publicKey, userId, now = Date.now()) {
  const timestamp = request.headers.get('X-StackShift-Timestamp') ?? ''
  const invocation = request.headers.get('X-StackShift-Invocation') ?? ''
  const signature = Buffer.from(request.headers.get('X-StackShift-Signature') ?? '', 'base64')
  const keyBytes = Buffer.from(publicKey, 'base64')
  const age = now - Number(timestamp) * 1000
  if (!/^\d+$/.test(timestamp) || !Number.isFinite(age) || age > 300_000 || age < -60_000 ||
      !invocation || keyBytes.length !== 32 || signature.length !== 64 || !userId) {
    throw new Error('Invalid StackShift invocation')
  }
  const raw = Buffer.from(await request.arrayBuffer())
  const key = createPublicKey({
    key: Buffer.concat([Buffer.from('302a300506032b6570032100', 'hex'), keyBytes]),
    format: 'der', type: 'spki',
  })
  if (!verify(null, Buffer.concat([Buffer.from(`${timestamp}\n${invocation}\n`), raw]), key, signature)) {
    throw new Error('Invalid StackShift signature')
  }
  const body = JSON.parse(raw.toString('utf8'))
  if (body.userId !== userId || !invocation.startsWith(`${body.runId}:`)) {
    throw new Error('StackShift invocation belongs to another account or run')
  }
  return body
}

Authenticated handler route

import { verifyInvocation } from './verify-invocation.mjs'
import { stackshift } from '@/lib/stackshift'

export async function POST(request: Request) {
  let invocation
  try {
    invocation = await verifyInvocation(request,
      process.env.STACKSHIFT_JOBS_PUBLIC_KEY!,
      process.env.STACKSHIFT_ACCOUNT_ID!)
  } catch {
    return new Response('Unauthorized', { status: 401 })
  }
  const { status, body } = await stackshift.handleInvocation(invocation)
  return Response.json(body, { status })
}

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. Execution is at least once. Make external side effects idempotent.

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',
  }
)

import stackshift "github.com/stackshiftCloud/jobs-go"

client, err := stackshift.New(stackshift.Options{
  APIKey: os.Getenv("STACKSHIFT_API_KEY"),
})
if err != nil {
  return err
}

_, err = client.Start(ctx, "send-verification-email", map[string]any{
  "userId": "user_123",
  "email": "ada@example.com",
}, &stackshift.StartOptions{
  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.

​Goal

​Prerequisites

​Workflow

​SDK 0.2.0 callback authentication

​Reliability update awaiting rollout

​Verify callbacks before executing jobs

​What Durable Jobs is

​Short example

​Mental model

​Expected result

​Related guides

Quick Start

Idempotency

Event Waiting + Correlation

Goal

Prerequisites

Workflow

SDK 0.2.0 callback authentication

Reliability update awaiting rollout

Verify callbacks before executing jobs

What Durable Jobs is

Short example

Mental model

Expected result

Related guides