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
delaySecondsandrunAt
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.
| Option | What you run | Good at | Watch out for |
|---|---|---|---|
after() in Next.js | Nothing extra | Small follow-ups like logging or a welcome email | Runs inside the same function and its time limit. No retries, no delay, no status. |
| BullMQ + Redis worker | Redis and a long-running worker process | High volume, priorities, rate limiting per queue, job flows, full control | Needs a server that is always on, which serverless hosts don't give you. You run and monitor it. |
| CloudHike Jobs | Nothing extra: your job is a route handler | Long calls with retries, delays up to 7 days, cron schedules, webhooks, a runs dashboard | Your 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
- Sign in at cloudhike.dev, open your project and click Deploy on the Jobs card.
- Click Copy as .env and paste
JOBS_API_URLandJOBS_API_KEYinto.env.local. - Add
APP_URL, the public address the job runner will call, and yourDATABASE_URL.
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.appThe 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.
npm install pg server-only
npm install -D @types/pgCreate 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.
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()
);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.
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.
"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.
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 answer | What the runner does |
|---|---|
Any 2xx | The run is succeeded. Your JSON body becomes response.body. |
429 or 5xx, or a network error | Tries again, up to retries extra times. |
Any other status, such as 400 or 404 | The run is failed right away. Use these for errors a retry can't fix. |
No answer before timeoutSeconds | The 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.
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.
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 });
}"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.
| Field | Use it for |
|---|---|
retries | Extra tries after a network error, 429 or 5xx, from 0 to 5. Use 0 for work that must never run twice. |
timeoutSeconds | How long the runner waits for your answer. Keep it within your route's maxDuration and your plan's limit. |
delaySeconds | Start later, for example a follow-up check in 10 minutes. Up to 7 days. |
runAt | Start at an exact time, such as 2026-11-20T09:00:00Z, up to 7 days ahead. Send this or delaySeconds, not both. |
callbackUrl | Where the finished run is posted. null sends no webhook for this run. |
"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_URLandDATABASE_URLto your host's environment variables, withAPP_URLset to your production domain. - Verify
x-cloudhike-signatureon every route the runner calls, including the webhook, and refuse old timestamps. - Make job routes safe to run twice. Check
x-cloudhike-run-idand use upserts. - Return
4xxfor errors a retry can't fix, so you don't pay for pointless retries. - Set
maxDurationon each job route, and keeptimeoutSecondsbelow it. - Check ownership in your status route so users only see their own jobs.
- Handle
429when 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
failedto 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.
