Skip to content
Redis & Jobs guide

Run Background Jobs in Next.js (No Worker Server Needed)

Move slow work out of your Next.js requests. A hosted job runner calls a route handler in your app, retries it when it fails and posts the result back to a webhook, so there is no queue or worker process to run.

25 min Intermediate Markdown for AI

What you'll build

  • A Server Action that starts a background job and returns at once
  • A job route handler that only accepts signed calls from the job runner
  • Safe handling of retries and duplicate calls with x-cloudhike-run-id
  • A webhook that saves the result, and a UI that polls for status
  • Delayed and scheduled runs with delaySeconds and runAt

Before you start

  • A Next.js 16 app using the App Router
  • A Postgres database to store job state (any Postgres works; the code uses pg)
  • A public URL for your app: a deployed preview, or a tunnel such as ngrok while you develop
  • A free CloudHike.dev account

Why slow work does not belong in a request, and your options

Some work takes longer than a user should wait: generating a PDF report, calling an AI model several times, importing a big CSV, or syncing with a slow third-party API. If you do it inside the request, three things go wrong.

  • Timeouts. Serverless hosts stop a function after a set time. Past that, the work dies halfway and the user sees an error.
  • No retries. If the third-party API has a hiccup, the request fails and nobody tries again.
  • A frozen UI. The user stares at a spinner, and if they close the tab, the work may stop with it.

The classic fix is a queue (often Redis with BullMQ) plus a worker process that runs all the time. That works well, but serverless hosts like Vercel have nowhere to run a long-lived worker, so you end up running a second server.

This guide uses CloudHike Jobs instead. It is HTTP-based: you ask it to call a URL, it answers at once with a run id, then its worker calls your URL, waits for the answer, retries on failure and posts the finished run to your webhook. Your job code is just a normal Next.js route handler.

Your job route still runs on your host, so it still has your host's time limit. Set maxDuration on that route as high as your plan allows. What you gain is that the user's request returns at once, failed calls are retried, and the work can start later. For work longer than any function limit, split it into several smaller runs.

How this compares to BullMQ and other options

There is no single right answer. Here is a fair look at the common choices for background work in a Next.js app.

OptionWhat you runGood atWatch out for
after() in Next.jsNothing extraSmall follow-ups like logging or a welcome emailRuns inside the same function and its time limit. No retries, no delay, no status.
BullMQ + Redis workerRedis and a long-running worker processHigh volume, priorities, rate limiting per queue, job flows, full controlNeeds a server that is always on, which serverless hosts don't give you. You run and monitor it.
CloudHike JobsNothing extra: your job is a route handlerLong calls with retries, delays up to 7 days, cron schedules, webhooks, a runs dashboardYour job route still has your host's time limit, and it must be reachable at a public URL.

If you already run a server next to your app, BullMQ is a great choice, and CloudHike's Redis works with it. If your app is fully serverless, an HTTP job runner saves you a whole service to operate.

Step 1: Deploy Jobs and create the tables

  1. Sign in at cloudhike.dev, open your project and click Deploy on the Jobs card.
  2. Click Copy as .env and paste JOBS_API_URL and JOBS_API_KEY into .env.local.
  3. Add APP_URL, the public address the job runner will call, and your DATABASE_URL.
.env.local
Shell
JOBS_API_URL=https://...
JOBS_API_KEY=...
DATABASE_URL=postgresql://...
# Public address of this app. In development, a tunnel such as
# "ngrok http 3000" gives you one.
APP_URL=https://your-tunnel.ngrok-free.app

The job runner refuses localhost and private network addresses, because it calls your URL from the internet. While you develop, run a tunnel to your dev server and put its address in APP_URL.

JOBS_API_KEY both starts runs and signs every request the runner sends you, so keep it on the server. Never give it a NEXT_PUBLIC_ prefix.

Shell
npm install pg server-only
npm install -D @types/pg

Create two tables: reports holds what the user sees, and job_results remembers which runs already finished so a repeated call does not redo the work.

schema.sql
SQL
create table reports (
  id uuid primary key default gen_random_uuid(),
  user_id text not null,
  status text not null default 'queued', -- queued, done, failed
  run_id text,
  result jsonb,
  error text,
  created_at timestamptz not null default now(),
  finished_at timestamptz
);

create table job_results (
  run_id text primary key,
  result jsonb not null,
  created_at timestamptz not null default now()
);
lib/db.ts
TypeScript
import "server-only";
import { Pool } from "pg";

// One small pool per process, kept across dev hot reloads.
const globalForDb = globalThis as unknown as { pool?: Pool };
export const pool = globalForDb.pool ?? new Pool({ connectionString: process.env.DATABASE_URL, max: 5 });
if (process.env.NODE_ENV !== "production") globalForDb.pool = pool;

Step 2: Start a run from a Server Action

Put every call to the Jobs API in one server-only file. It starts runs, reads them and checks the signature on requests the runner sends you.

lib/jobs.ts
TypeScript
import "server-only";
import { createHmac, timingSafeEqual } from "node:crypto";

export type RunStatus = "queued" | "running" | "succeeded" | "failed" | "cancelled";

export type JobRun = {
  id: string;
  status: RunStatus;
  attempts: number;
  response: { status: number; body: unknown; truncated: boolean } | null;
  error: string | null;
};

type StartRun = {
  url: string;
  method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
  headers?: Record<string, string>;
  body?: unknown;
  timeoutSeconds?: number;
  retries?: number;
  delaySeconds?: number;
  runAt?: string;
  callbackUrl?: string | null;
};

export class JobsError extends Error {
  constructor(message: string, public status: number) {
    super(message);
  }
}

async function jobsApi(path: string, init: RequestInit = {}) {
  const res = await fetch(`${process.env.JOBS_API_URL}${path}`, {
    ...init,
    headers: {
      "content-type": "application/json",
      "x-api-key": process.env.JOBS_API_KEY!,
    },
  });
  if (!res.ok) {
    const text = await res.text().catch(() => "");
    throw new JobsError(text || res.statusText, res.status);
  }
  return res.json();
}

export function startRun(run: StartRun): Promise<{ id: string; status: "queued"; statusUrl: string }> {
  return jobsApi("/runs", { method: "POST", body: JSON.stringify(run) });
}

export function getRun(id: string): Promise<JobRun> {
  return jobsApi(`/runs/${encodeURIComponent(id)}`);
}

// x-cloudhike-signature is "t=<unix seconds>,v1=<hex>", where v1 is
// HMAC-SHA256 of "<t>.<raw body>" with JOBS_API_KEY.
export function verifySignature(rawBody: string, header: string | null) {
  const parts = Object.fromEntries((header ?? "").split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false; // refuse old timestamps
  const expected = createHmac("sha256", process.env.JOBS_API_KEY!).update(`${t}.${rawBody}`).digest("hex");
  return expected.length === parts.v1?.length && timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

Now the Server Action. It saves a reports row, asks the runner to call your job route with the report id, and returns right away. The reportId also goes into the callback URL, so the webhook knows which row to update.

app/reports/actions.ts
TypeScript
"use server";

import { pool } from "@/lib/db";
import { JobsError, startRun } from "@/lib/jobs";

export type StartResult = { reportId: string } | { error: string };

export async function startReport(): Promise<StartResult> {
  const userId = "demo-user"; // Replace with the signed-in user's id.

  const { rows } = await pool.query<{ id: string }>(
    "insert into reports (user_id) values ($1) returning id",
    [userId],
  );
  const reportId = rows[0].id;

  try {
    const run = await startRun({
      url: `${process.env.APP_URL}/api/jobs/generate-report`,
      body: { reportId },
      timeoutSeconds: 300,
      retries: 3,
      callbackUrl: `${process.env.APP_URL}/api/jobs/webhook?reportId=${reportId}`,
    });
    await pool.query("update reports set run_id = $1 where id = $2", [run.id, reportId]);
    return { reportId };
  } catch (err) {
    await pool.query("update reports set status = 'failed', error = $1, finished_at = now() where id = $2", [
      "Could not start the job",
      reportId,
    ]);
    if (err instanceof JobsError && err.status === 429) {
      return { error: "Too many reports are running. Please try again in a minute." };
    }
    console.error(err);
    return { error: "Could not start the report. Please try again." };
  }
}

The runner answers with status 202 and a run in the queued state. The work has not started yet, which is why the action is fast.

Step 3: Write the job route and verify the signature

The job itself is a route handler. Anyone on the internet can reach this URL, so the first thing it does is check x-cloudhike-signature. Read the body with request.text(): the signature covers the raw bytes, and parsing JSON first would change them.

app/api/jobs/generate-report/route.ts
TypeScript
import { pool } from "@/lib/db";
import { verifySignature } from "@/lib/jobs";

// Your host stops the function after this many seconds. Use what your plan
// allows, and keep timeoutSeconds in startRun() no higher than this.
export const maxDuration = 300;

async function generateReport(reportId: string) {
  // Your slow work goes here: queries, AI calls, building a file...
  await new Promise((r) => setTimeout(r, 20_000));
  return { reportId, rows: 1234, generatedAt: new Date().toISOString() };
}

export async function POST(request: Request) {
  const raw = await request.text();
  if (!verifySignature(raw, request.headers.get("x-cloudhike-signature"))) {
    return new Response("bad signature", { status: 401 });
  }

  const runId = request.headers.get("x-cloudhike-run-id");
  const { reportId } = JSON.parse(raw) as { reportId?: string };
  if (!runId || !reportId) {
    return new Response("missing run id or report id", { status: 400 }); // 4xx is final, not retried
  }

  // Runs are delivered at least once. If this run already finished,
  // answer with the saved result instead of doing the work again.
  const done = await pool.query("select result from job_results where run_id = $1", [runId]);
  if (done.rows[0]) return Response.json(done.rows[0].result);

  try {
    const result = await generateReport(reportId);
    await pool.query(
      "insert into job_results (run_id, result) values ($1, $2) on conflict (run_id) do nothing",
      [runId, JSON.stringify(result)],
    );
    return Response.json(result); // any 2xx marks the run as succeeded
  } catch (err) {
    console.error(err);
    return new Response("report failed", { status: 500 }); // 5xx is retried
  }
}

The status code you return tells the runner what happened:

Your answerWhat the runner does
Any 2xxThe run is succeeded. Your JSON body becomes response.body.
429 or 5xx, or a network errorTries again, up to retries extra times.
Any other status, such as 400 or 404The run is failed right away. Use these for errors a retry can't fix.
No answer before timeoutSecondsThe run is failed with a timeout. Timeouts are not retried.

The job_results check stops repeat work after a run has finished. A retry after a crash halfway through will still run the work again, so make each step safe to repeat (use upserts, not plain inserts). If a step can never run twice, such as charging a card, start that run with retries: 0.

Step 4: Receive the result on a webhook

When the run ends, the runner POSTs the finished run to your callbackUrl, with the same JSON you get from polling and the same signature header. Answer with any 2xx. Other answers are retried a few times, so this handler must be safe to call twice too.

app/api/jobs/webhook/route.ts
TypeScript
import { pool } from "@/lib/db";
import { verifySignature, type JobRun } from "@/lib/jobs";

export async function POST(request: Request) {
  const raw = await request.text();
  if (!verifySignature(raw, request.headers.get("x-cloudhike-signature"))) {
    return new Response("bad signature", { status: 401 });
  }

  const run = JSON.parse(raw) as JobRun;
  const reportId = new URL(request.url).searchParams.get("reportId");
  if (!reportId) return new Response("ok"); // a run this app did not start with a report

  const ok = run.status === "succeeded";
  // "finished_at is null" makes a repeated webhook a no-op.
  await pool.query(
    `update reports
        set status = $1, run_id = $2, result = $3, error = $4, finished_at = now()
      where id = $5 and finished_at is null and (run_id is null or run_id = $2)`,
    [
      ok ? "done" : "failed",
      run.id,
      ok ? JSON.stringify(run.response?.body ?? null) : null,
      ok ? null : (run.error ?? run.status),
      reportId,
    ],
  );
  return new Response("ok");
}

Don't want to pass callbackUrl on every run? Set a webhook URL under Jobs → Manage → Webhook in the dashboard, and every run without its own callbackUrl is posted there. From that page you can also send a signed test event to check your handler. See Webhooks for the details.

Step 5: Show progress in the UI

The browser can't call the Jobs API (that would need your key), so give it a small status route. It reads the reports row, and while the report is still waiting, asks the runner whether the run is queued or running.

app/api/reports/[id]/route.ts
TypeScript
import { pool } from "@/lib/db";
import { getRun } from "@/lib/jobs";

const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;

export async function GET(_request: Request, { params }: { params: Promise<{ id: string }> }) {
  const { id } = await params;
  if (!UUID.test(id)) return Response.json({ error: "Not found" }, { status: 404 });

  // In a real app, also check that the report belongs to the signed-in user.
  const { rows } = await pool.query("select status, run_id, result, error from reports where id = $1", [id]);
  const report = rows[0];
  if (!report) return Response.json({ error: "Not found" }, { status: 404 });

  if (report.status === "queued" && report.run_id) {
    try {
      const run = await getRun(report.run_id);
      return Response.json({ status: run.status }); // "queued" or "running"
    } catch (err) {
      console.error(err);
    }
  }
  return Response.json({ status: report.status, result: report.result, error: report.error });
}
app/reports/page.tsx
TSX
"use client";

import { useEffect, useState, useTransition } from "react";
import { startReport } from "./actions";

type Status = { status: string; result?: { rows: number; generatedAt: string }; error?: string };

export default function ReportsPage() {
  const [reportId, setReportId] = useState<string | null>(null);
  const [state, setState] = useState<Status | null>(null);
  const [message, setMessage] = useState("");
  const [starting, start] = useTransition();

  useEffect(() => {
    if (!reportId) return;
    const timer = setInterval(async () => {
      const res = await fetch(`/api/reports/${reportId}`);
      if (!res.ok) return;
      const next: Status = await res.json();
      setState(next);
      if (next.status === "done" || next.status === "failed") clearInterval(timer);
    }, 2000);
    return () => clearInterval(timer);
  }, [reportId]);

  const busy = starting || (!!reportId && state?.status !== "done" && state?.status !== "failed");

  return (
    <main className="mx-auto grid max-w-md gap-4 p-8">
      <button
        disabled={busy}
        onClick={() =>
          start(async () => {
            setState({ status: "queued" });
            setMessage("");
            const res = await startReport();
            if ("error" in res) {
              setState(null);
              setMessage(res.error);
            } else {
              setReportId(res.reportId);
            }
          })
        }
      >
        {busy ? "Working…" : "Generate report"}
      </button>

      {state?.status === "queued" && <p>Waiting to start…</p>}
      {state?.status === "running" && <p>Generating your report. You can leave this page.</p>}
      {state?.status === "done" && <p>Done: {state.result?.rows} rows.</p>}
      {state?.status === "failed" && <p role="alert">The report failed: {state.error}</p>}
      {message && <p role="alert">{message}</p>}
    </main>
  );
}

Polling every two seconds is simple and cheap for a page that only one user watches. Because the result is saved by the webhook, the user can close the tab and come back later.

Step 6: Retries, delays and scheduled runs

A few fields on startRun() cover most real needs. The full list is in Start a run.

FieldUse it for
retriesExtra tries after a network error, 429 or 5xx, from 0 to 5. Use 0 for work that must never run twice.
timeoutSecondsHow long the runner waits for your answer. Keep it within your route's maxDuration and your plan's limit.
delaySecondsStart later, for example a follow-up check in 10 minutes. Up to 7 days.
runAtStart at an exact time, such as 2026-11-20T09:00:00Z, up to 7 days ahead. Send this or delaySeconds, not both.
callbackUrlWhere the finished run is posted. null sends no webhook for this run.
app/trials/actions.ts
TypeScript
"use server";

import { startRun } from "@/lib/jobs";

// Check on a new trial user one day after sign-up.
export async function scheduleTrialCheck(userId: string) {
  await startRun({
    url: `${process.env.APP_URL}/api/jobs/trial-check`,
    body: { userId },
    delaySeconds: 24 * 60 * 60,
    retries: 2,
    callbackUrl: null, // nothing to save, so skip the webhook
  });
}

Changed your mind? POST {JOBS_API_URL}/runs/<id>/cancel cancels a run. A queued run never starts; a running one is left to finish, but its result is dropped and no webhook is sent.

For work that repeats, such as a nightly cleanup or a daily digest, create a recurring schedule with a cron expression instead of starting runs yourself. The scheduled email reminders guide walks through one.

Production checklist

  • Add JOBS_API_URL, JOBS_API_KEY, APP_URL and DATABASE_URL to your host's environment variables, with APP_URL set to your production domain.
  • Verify x-cloudhike-signature on every route the runner calls, including the webhook, and refuse old timestamps.
  • Make job routes safe to run twice. Check x-cloudhike-run-id and use upserts.
  • Return 4xx for errors a retry can't fix, so you don't pay for pointless retries.
  • Set maxDuration on each job route, and keep timeoutSeconds below it.
  • Check ownership in your status route so users only see their own jobs.
  • Handle 429 when starting runs. Plan limits, such as runs per minute and runs in progress, are on the Jobs limits and pricing pages.
  • Watch the Runs page in the dashboard after launch, and filter by failed to spot problems early.

Frequently asked questions

How do I run background jobs in Next.js on Vercel?

Vercel has no long-running worker process, so a classic queue worker has nowhere to live. Use an HTTP-based job runner instead: your server starts a run, the runner calls one of your route handlers in the background, retries it if it fails and sends the result to a webhook.

Can I use BullMQ with Next.js?

Yes, but BullMQ needs a worker process that runs all the time and stays connected to Redis. You can add jobs from Next.js, but the worker has to run on a separate server or container, not in serverless functions.

What is the difference between after() and a background job?

after() runs code after the response is sent, but inside the same function, with the same time limit and no retries. A background job runs in its own request, can be retried, delayed or scheduled, and has a status you can check later.

What happens if my job route is called twice?

Job runners deliver at least once, so in rare cases your route can be called twice for the same run. Every call carries the same x-cloudhike-run-id header. Save finished run ids and skip the work if you have already done it.

How long can a background job run?

It depends on two limits: how long the job runner waits (set with timeoutSeconds, up to your plan's maximum) and how long your host lets the route handler run (maxDuration). The shorter one wins. Split very long work into several runs.