Scheduled Jobs

Taskhook provides flexible job scheduling capabilities that let you execute tasks at specific times or on recurring schedules. Whether you need to send a follow-up email in 24 hours or generate monthly reports, scheduled jobs make it easy to manage time-based task execution.

Overview

Taskhook supports two main types of scheduled jobs:

• One-off delayed tasks - Execute a single task after a specified delay or at a specific time
• Recurring schedules - Run tasks repeatedly on a defined schedule using cron expressions

One-off Delayed Tasks

When you need to execute a task at a future time, you can create a delayed task using either relative delays or absolute execution times.

Relative Delays

Specify how long to wait before executing the task:

await taskhookClient.tasks.create({
  target: 'https://api.example.com/process',
  execute_after: 'PT1H', // Run in 1 hour
  payload: { userId: '123' },
})

Absolute Execution Times

Schedule a task to run at a specific time:

await taskhookClient.tasks.create({
  target: 'https://api.example.com/process',
  execute_after: '2024-03-01T15:00:00Z', // Run at absolute UTC time
  payload: { userId: '123' },
})

Common Use Cases

• Send follow-up emails hours/days after user actions
• Schedule content publishing at specific times
• Clean up temporary resources after a delay

Recurring Schedules

For tasks that need to run on a regular basis, Taskhook provides cron-like recurring schedules.

Creating Recurring Schedules

You can create recurring schedules either through:

• The Taskhook Dashboard
• The Schedules API (if you prefer to have configuration as code or need dynamic scheduled tasks)

Schedule Configuration

Each schedule defines:

• A cron expression (e.g., 0 9 * * * for daily at 9 AM)
• Timezone for interpreting the cron expression
• Optional start and end dates
• Task template (callback URL, payload, etc.)

await taskhookClient.schedules.create({
  cron: '0 9 * * *',
  timezone: 'America/New_York',
  task_template: {
    target: 'https://api.example.com/daily-report',
    payload: { type: 'daily' },
  },
})

Task Creation Behavior

• New tasks won't be created if previous tasks are still processing
• The system can recover and create missed tasks during the downtime

Safe Server Deployment

When creating schedules via API (e.g., during server startup), use the unique_id parameter to prevent duplicate schedules:

await taskhookClient.schedules.create({
  unique_id: 'daily-report-schedule',
  cron: '0 9 * * *',
  // ... other config
})

This allows you to safely include schedule creation in your deployment process - only new schedules will be created, and existing ones will be updated if their configuration changes.

Execution Time Guarantees

When scheduling tasks, it's important to understand that the specified execution times represent the earliest possible execution times. Actual execution may be delayed due to various factors:

• Rate limits you have defined
• Request execution errors and automatic retries
• Network issues or delays
• System load, queue depth, and other infrastructure factors

In most cases, tasks will execute within a few seconds of their scheduled time. However, Taskhook may not be suitable for applications with strict real-time requirements where any additional delay, even if rare, is unacceptable.

Best Practices

1. Handle Execution Windows

   • Set expires_at for time-sensitive tasks
   • Tasks won't execute if they expire before processed successfully

2. Plan for Failures

   • Tasks automatically retry with exponential backoff
   • Configure custom retry policies for special cases

3. Monitor Schedule Health

   • Use the dashboard to monitor execution history
   • Set up alerts for failed tasks that need attention