Background Jobs

Background jobs are essential for modern applications that need to handle time-consuming operations without affecting user experience. Taskhook provides a robust, HTTP-based solution for running these operations asynchronously.

What are background jobs?

Background jobs are operations that run independently of your application's main request-response cycle. Instead of processing everything immediately when a user makes a request, you can offload time-consuming tasks to run in the background while quickly responding to the user.

Common use cases include:

• Sending emails or notifications
• Processing uploaded files or images
• Generating reports or analytics
• Syncing data with external services

How Taskhook handles background jobs

In Taskhook, background jobs are implemented using tasks. Each task represents a unit of work that needs to be performed asynchronously. Here's how it works:

1. Your application creates a task through Taskhook's API, specifying:

   • A callback URL where your job handler is hosted
   • The payload containing the job data
   • Optional timing parameters (delays, schedules)

2. Taskhook queues the task and manages its execution:

   • Sends an HTTP request to your callback URL when it's time to run
   • Handles retries automatically if the job fails
   • Provides status updates and execution logs

3. Your application processes the task by:

   • Receiving the HTTP callback from Taskhook
   • Performing the required work
   • Responding with appropriate status codes (200 for success, 500 for failure)

Example implementation

Let's look at a practical example: processing user uploads in the background.

import TaskhookClient from '@taskhook/client'

const client = new TaskhookClient(process.env.TASKHOOK_API_KEY)

// When user uploads a file
app.post('/uploads', async (req, res) => {
  // Save the file and get its ID
  const fileId = await saveFile(req.files[0])

  // Create a background job to process it
  await client.tasks.create({
    target: {
      url: 'https://api.yourapp.com/jobs/process-upload',
      headers: {
        'X-Secret-Token': process.env.WEBHOOK_SECRET,
      },
    },
    payload: { fileId },
  })

  // Respond to user immediately
  res.json({ status: 'processing' })
})

Key features for background jobs

Reliable execution

Taskhook implements a sophisticated retry strategy that ensures your jobs complete successfully:

• Up to 25 retry attempts over approximately 7 days
• Progressive backoff with random jitter
• Automatic retry on common failure scenarios
• Detailed execution logs for debugging

Flexible timing

Control when your jobs run with multiple timing options:

• Immediate execution
• Delayed execution (execute_after_seconds or execute_after)
• Expiration timing (expires_after_seconds or expires_at)
• Rate limiting to control concurrency

Monitoring and observability

Track your background jobs through:

• Real-time status updates
• Detailed execution logs
• Callback response data
• Dashboard monitoring

Next steps

Now that you understand how background jobs work in Taskhook, explore these topics to make the most of the platform:

• Tasks API Reference for detailed endpoint documentation
• Rate Limiters to control job concurrency
• Webhook Security for securing your job endpoints
• Best Practices for reliable background job processing