HOW TO RUN SCHEDULED JOBS WITH YOUR VERCEL APP ENDPOINT
How to run scheduled jobs with your Vercel app endpoint
Vercel functions run only on request — give your API route a clock. Fire signed webhook deliveries at your Vercel endpoint on any cron expression, with retries, timezones, and a full activity trail.
Your Vercel app is a pile of request-shaped code — route handlers, server components, functions that wake when a request arrives and sleep after. Nothing in it owns a clock. Any “every night at 6” job needs a trigger from outside, and the two options are Vercel’s own Cron Jobs (a platform timer that GETs a path) or an external scheduler that POSTs a signed, structured event payload to your endpoint on any cron expression. This guide is the second pattern: a managed scheduler delivering to a Vercel route handler — what it gives you, exact code, and Vercel-specific gotchas.
First, what Vercel Cron Jobs do (and don’t)
Be fair to the platform timer: it’s free, zero-config, and right for same-deploy glue. But check the current behavior before you build anything meaningful on it:
| Vercel Cron Jobs | Signed webhook deliveries | |
|---|---|---|
| Request | GET to the path — empty body |
POST with your event payload in JSON |
| Payload | None — the route re-derives what to do | Events you defined (batched by subject) |
| Timezone | UTC only — “9am” shifts with the clock | Any timezone per schedule |
| Frequency (Hobby) | Once per day; more-frequent expressions fail deployment | Any cron expression, including free tier |
| Timing precision (Hobby) | Any time within the scheduled hour | Within the minute |
| Retries | No retry on failure, delivery is best-effort (occasionally skipped or duplicated) | Configurable retry policy with backoff, every attempt recorded |
| Observability | Runtime logs (1 hour on Hobby) | Full activity trail per delivery: status, latency, attempt, batch |
| Changing the schedule | Edit vercel.json → redeploy |
Dashboard or API call — no deploy |
When is the native cron still the right call? Sub-minute glue inside one deploy, no payload needed, nobody else will ever manage the schedule. For anything else — payloads, timezones, per-tenant batching, retries you can see, schedules your API or an AI agent can create — point an external scheduler at your route handler instead.
The pattern
Recurrence Cloud (scheduler) Your Vercel route handler
───────────────────────────── ──────────────────────────
cronExpr: "0 6 * * *" export async function POST
timezone: "America/Chicago" verify HMAC signature
events: [signed batch] ────POST────► read batch.events
X-Webhook-Signature process / fan out
X-Recurrence-Batch-Id return 2xx
The scheduler lives outside Vercel; your app stays ordinary. Rebuilds, rollbacks, and redeploys don’t touch the schedule.
Step 1: The receiving route handler
Next.js App Router route handlers are the target. This one verifies the signature first, then processes the batch — in either the Node.js or Edge runtime, because it uses only Web Crypto:
// app/api/scheduled/digest/route.ts
import { NextResponse } from "next/server";
// Work budget: 300s default/max on Hobby, configurable up to 800s on Pro
export const maxDuration = 300;
export async function POST(request: Request) {
const raw = await request.text();
// Signature first — never parse unverified payloads into domain logic
const signature = request.headers.get("X-Webhook-Signature");
const secret = process.env.WEBHOOK_SECRET;
if (!signature || !secret || !(await verifyHmac(raw, signature, secret))) {
return NextResponse.json({ error: "invalid signature" }, { status: 401 });
}
const batch = JSON.parse(raw);
// batch = {
// events: [ { id, subject, scheduleId, scheduleName, data }, ... or
// grouped: { subject, count, events: [...] } ],
// organizationId, appId, webhookId, batchId, attempt, firedAt
// }
// Retries reuse batchId — key dedup on (batchId, attempt) if a
// redelivery must be a no-op.
for (const group of batch.events ?? []) {
const events = Array.isArray(group.events) ? group.events : [group];
for (const event of events) {
await handleEvent(event, batch);
}
}
return NextResponse.json({ ok: true });
}
async function handleEvent(event: any, batch: any) {
switch (event.data.type) {
case "digest.send": /* ... */ break;
case "sync.run": /* ... */ break;
}
}
async function verifyHmac(raw: string, sigHex: string, secret: string) {
const key = await crypto.subtle.importKey(
"raw",
new TextEncoder().encode(secret),
{ name: "HMAC", hash: "SHA-256" },
false,
["sign"],
);
const digest = await crypto.subtle.sign(
"HMAC",
key,
new TextEncoder().encode(raw),
);
const hex = [...new Uint8Array(digest)]
.map((b) => b.toString(16).padStart(2, "0"))
.join("");
return hex === sigHex;
}
Two route rules matter:
- Export
POST— webhook deliveries are POSTs. If the same route already serves a Vercel CronGETexport, both can coexist and dispatch on method. - Keep the route dynamic — read a header (the signature check already does), so it isn’t cached or prerendered.
Set the secret as an environment variable (vercel env add WEBHOOK_SECRET, or the dashboard → Settings → Environment Variables) — and remember that environment variable changes only apply to new deployments, so redeploy after adding or rotating it.
Step 2: Point a schedule at the endpoint
Register the schedule, webhook, and first event in one API call:
curl -X POST https://api.recurrence.cloud/api/v1/schedules/with-webhook \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"schedule": {
"name": "nightly-digest",
"cronExpr": "0 6 * * *",
"timezone": "America/Chicago"
},
"webhook": {
"url": "https://yourapp.vercel.app/api/scheduled/digest",
"secret": "<the same value as WEBHOOK_SECRET>"
},
"event": {
"subject": "digest-prod",
"payload": { "type": "digest.send", "window": "overnight" }
},
"appId": "$APP_ID"
}'
At 6am Chicago time, the schedule fires and your handler receives a signed JSON batch:
{
"events": [
{ "id": "evt_01", "subject": "digest-prod", "scheduleName": "nightly-digest", "data": { "type": "digest.send", "window": "overnight" } }
],
"organizationId": "org_1",
"appId": "app_1",
"webhookId": "wh_1",
"batchId": "bat_01",
"attempt": 1,
"firedAt": "2025-11-30T12:00:00.500Z"
}
If the handler 500s or times out, the delivery retries on the schedule’s policy — shown to you in the activity trail with status codes and latencies, not a log line that expires in an hour.
Step 3: Test without waiting for the date
Preview deployments aren’t reliably invocable by schedulers — deliveries target your production URL. For testing:
# 1. Write the test body (matches the delivery shape your handler expects)
cat > body.json <<'EOF'
{"events":[{"id":"evt_test","subject":"digest-prod","data":{"type":"digest.send"}}],"batchId":"bat_test","attempt":1,"firedAt":"2025-11-30T12:00:00Z"}
EOF
# 2. Sign it with the same secret and fire
SIG=$(node -e 'console.log(require("node:crypto").createHmac("sha256",process.env.WEBHOOK_SECRET).update(require("node:fs").readFileSync("body.json")).digest("hex"))')
curl -X POST https://yourapp.vercel.app/api/scheduled/digest \
-H "Content-Type: application/json" \
-H "X-Webhook-Signature: $SIG" \
--data-binary @body.json
Or keep a development schedule pointed at a non-Vercel URL (a dev server, ngrok, or a bare next dev) and exercise the handler logic locally with the exact signed shape production delivers.
Vercel-specific gotchas for scheduled work
- Timeouts are hard stops. Work exceeding
maxDurationis killed with a 504 — and with native crons, nothing ever reports it. Design the handler to trigger and fan out: push events into a queue (Vercel Queues, Upstash QStash) or a durable workflow (Vercel Workflows) and return200while the real work continues. See event-chain patterns. - Don’t overlap long runs. If a job can outlive its interval, key work idempotently on
(batchId, attempt)so an overlap or duplicate delivery is harmless. - Timezones belong to the schedule, not the code. Vercel runs everything in UTC; the schedule carries the timezone, so “6am in Chicago” arrives at 6am Chicago — even across DST changes.
- Preview environments are a scheduling afterthought. One production schedule per endpoint keeps the activity trail meaningful; use the test-recipe above for previews.
- Secrets rotate without deploys on the scheduler side. Update the webhook’s secret in Recurrence Cloud, update the env var, redeploy once — the schedule URL never changes.
Recipes that fit a Vercel app
- Nightly digests per tenant — one schedule, events batched by tenant
subject, one POST per tenant run (batching by subject) - Hourly cache/revalidate sweeps —
0 * * * *with a revalidation payload; free-tier frequency Vercel’s Hobby cron doesn’t allow - Weekly report generation — Monday 8am in the company timezone, payload carries the report window
- Agent duties on a schedule — the batch ends in an MCP tool call or agent task; see scheduled MCP tool calls
Get started
- What is a scheduled webhook? — the pattern, in two minutes
- How to schedule edge functions with webhooks — the same pattern on Cloudflare Workers and Deno Deploy
- Cron expression cheat sheet — copy-paste expressions with timezone gotchas
FAQ
How do I run scheduled jobs on Vercel?
Two ways: Vercel Cron Jobs (entries in vercel.json that GET a route on production) or an external scheduler that POSTs a signed event payload to your endpoint on any cron expression. An external scheduler adds timezone support, minute-level frequency on all plans, retry policies, and a per-delivery audit trail.
How often can Vercel Cron Jobs run on the Hobby plan?
Once per day at most — cron expressions that would run more frequently fail the deployment. Hobby timing is also loose: a job scheduled at 1am may fire any time within the 1am hour, and every schedule runs in UTC. Pro and Enterprise can run as often as once per minute.
Does Vercel retry failed cron jobs?
No. If your function errors, times out (504), or the delivery is dropped, Vercel does not retry — the next attempt is the next scheduled run, and delivery is occasionally skipped or duplicated. An external webhook scheduler like Recurrence Cloud delivers with per-schedule retry policies and backoff, and records every attempt.
How do I secure a scheduled endpoint on Vercel?
Platform cron requests can be checked against a CRON_SECRET environment variable, which Vercel sends as an Authorization bearer header. For webhook deliveries, verify the HMAC-SHA256 signature of the raw body (X-Webhook-Signature) against your webhook secret and return 401 otherwise — an unsigned route that triggers jobs is a remote trigger anyone can fire.
Do scheduled jobs work on Vercel preview deployments?
No. Both Vercel Cron Jobs and external schedulers reliably target your production deployment. For preview environments, create separate schedules pointing at the preview URL, or test the route manually with curl.
Can a scheduled job run longer than the function timeout?
Not in one invocation — Vercel terminates functions at maxDuration (300s default and max on Hobby, up to 800s on Pro). Treat the scheduled delivery as a trigger: return fast, push the work into a queue or a workflow, and let a second worker finish it.