Background Jobs | Sylphx Documentation

Immediate Jobs

Run tasks in background

Delayed Jobs

Schedule for later

Cron Jobs

Recurring schedules

Auto Retry

Exponential backoff

Overview

The jobs service lets you schedule background tasks to run asynchronously. Perfect for sending emails, processing data, generating reports, or any work that shouldn't block your main request.

Schedule a Job

Schedule a job to run immediately or after a delay:

import { platform } from '@/lib/platform'

// Run immediately in the background
const job = await platform.jobs.schedule({
  url: 'https://myapp.com/api/jobs/send-email',
  body: {
    to: user.email,
    template: 'welcome',
  },
})

// Run after a delay
const delayedJob = await platform.jobs.schedule({
  url: 'https://myapp.com/api/jobs/follow-up',
  body: { userId: user.id },
  delay: 3600, // 1 hour in seconds
})

console.log(job.id) // Job ID for tracking

Job Handler

Create an endpoint to handle the job:

app/api/jobs/send-email/route.ts

import { platform } from '@/lib/platform'
import { NextRequest } from 'next/server'

export async function POST(req: NextRequest) {
  // Verify the request came from Sylphx
  const isValid = await platform.jobs.verifyRequest(req)
  if (!isValid) {
    return new Response('Unauthorized', { status: 401 })
  }

  const { to, template } = await req.json()

  // Do the work
  await sendEmail({ to, template })

  // Return success
  return new Response('OK', { status: 200 })
}

// Disable body parsing if needed for large payloads
export const config = {
  api: { bodyParser: false },
}

Recurring Jobs (Cron)

Schedule recurring jobs with cron expressions:

// Run every day at 9am UTC
const dailyJob = await platform.jobs.schedule({
  url: 'https://myapp.com/api/jobs/daily-report',
  cron: '0 9 * * *',
  body: { type: 'daily' },
})

// Run every hour
const hourlyJob = await platform.jobs.schedule({
  url: 'https://myapp.com/api/jobs/cleanup',
  cron: '0 * * * *',
})

// Run every Monday at 6am
const weeklyJob = await platform.jobs.schedule({
  url: 'https://myapp.com/api/jobs/weekly-digest',
  cron: '0 6 * * 1',
})

Property	Type	Description
`* * * * *`	`pattern`	Every minute
`0 * * * *`	`pattern`	Every hour
`0 0 * * *`	`pattern`	Every day at midnight
`0 9 * * 1-5`	`pattern`	Weekdays at 9am
`0 0 1 * *`	`pattern`	First of every month

Job Status

Check the status of a scheduled job:

const status = await platform.jobs.getStatus(jobId)

console.log(status)
// {
//   id: 'job_abc123',
//   status: 'completed', // 'pending' | 'running' | 'completed' | 'failed'
//   createdAt: '2024-01-15T10:00:00Z',
//   startedAt: '2024-01-15T10:00:01Z',
//   completedAt: '2024-01-15T10:00:05Z',
//   attempts: 1,
//   result: { success: true },
// }

Cancel Jobs

Cancel a pending or recurring job:

// Cancel a specific job
await platform.jobs.cancel(jobId)

// Cancel a recurring job
await platform.jobs.cancel(cronJobId)

Retries

Configure automatic retries for failed jobs:

const job = await platform.jobs.schedule({
  url: 'https://myapp.com/api/jobs/process',
  body: { data: 'value' },
  retries: {
    maxAttempts: 3,
    backoff: 'exponential', // 'linear' | 'exponential'
    initialDelay: 60,       // 1 minute
    maxDelay: 3600,         // 1 hour max
  },
})

Retry Behavior

Jobs are retried if your handler returns a 5xx status code or times out. Return 4xx for permanent failures that shouldn't be retried.

Timeout

Set a maximum execution time:

const job = await platform.jobs.schedule({
  url: 'https://myapp.com/api/jobs/long-process',
  body: { ... },
  timeout: 300, // 5 minutes max
})

Default timeout is 30 seconds. Maximum is 15 minutes.

Common Use Cases

Email sending

Queue emails instead of blocking requests

Data processing

Process uploads in the background

Report generation

Generate PDFs or exports async

Webhooks

Reliable webhook delivery with retries

Scheduled tasks

Daily cleanups, weekly reports

Notifications

Send notifications without blocking

Push Notifications

Send web push notifications

Error Tracking

Monitor and capture errors