Getting Started

On this page

Dispatched is a serverless-first background job queue that lets you handle asynchronous tasks without managing infrastructure. This guide will walk you through setting up and using Dispatched in your application.

What is Dispatched?

Dispatched is a fully managed service that allows you to:

  • Queue background jobs using simple HTTP requests
  • Schedule jobs to run in the future (up to 1 year ahead)
  • Automatically retry failed jobs with smart backoff
  • Process jobs through webhooks in your application

Perfect for serverless platforms like Vercel, Netlify, and Cloudflare Workers, Dispatched eliminates the complexity of managing job queues while providing enterprise-grade reliability.

Quick Start

1. Create Your Account

  1. Sign up at dispatched.dev
  2. Create a team in Settings > Team
  • Teams help organize your projects and manage access
  • You can create multiple teams for different projects or organizations

2. Get Your API Key

  1. Go to Settings > API Keys
  2. Click "Create API Key"
  3. Give your key a descriptive name (e.g., "Production API Key")
  4. Copy and securely store your API key
# Example of storing your API key in a .env file
DISPATCHED_API_KEY=disp_k1_xxxxxxxxxxxx

3. Configure Your Webhook

  1. Navigate to Settings > Webhook
  2. Add your webhook URL where Dispatched will send job notifications
  3. Save the provided Webhook Secret securely
# Store in your .env file
DISPATCHED_WEBHOOK_SECRET=disp_whsec_xxxxxxxxxxxx

4. Dispatch Your First Job

Here's a complete example of queuing a job and handling its webhook:

# Queue a job
curl -X POST https://dispatched.dev/api/jobs/dispatch \
  -H "Authorization: Bearer ${DISPATCHED_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {
      "task": "send_welcome_email",
      "userId": "123",
      "email": "user@example.com"
    }
  }'

Response:

{
  "jobId": "job_123456789abc",
  "status": "QUEUED"
}

5. Handle Webhook Callbacks

Create an endpoint in your application to process the webhook:

// Example Express.js webhook handler
app.post('/webhook', express.json(), (req, res) => {
  const webhookSecret = process.env.DISPATCHED_WEBHOOK_SECRET;

  // Verify webhook authenticity
  if (req.headers.authorization !== `Bearer ${webhookSecret}`) {
    return res.status(401).json({ error: 'Unauthorized' });
  }

  const { jobId, attemptId, attemptNumber, payload } = req.body;

  // Process the job
  try {
    // Handle the job payload
    console.log(`Processing job ${jobId} with attempt ${attemptId} attemptNumber ${attemptNumber}`);

    // Perform your task here
    await processJob(payload);

    // Return success
    res.status(200).json({ status: 'success' });
  } catch (error) {
    // Job will be retried automatically
    res.status(500).json({ error: error.message });
  }
});

Job Lifecycle

  1. Queue - Job is submitted via API
  2. Process - Dispatched sends the job to your webhook
  3. Complete - Your webhook returns 200/201 status
  4. Retry - If processing fails, Dispatched retries up to 3 times

Next Steps

Now that you've set up Dispatched, you can:

  1. Explore the API Reference for detailed endpoints and options
  2. Learn about Advanced Features like job scheduling
  3. Review Best Practices for production use
  4. Check Pricing & Limits for your subscription

Need Help?

Remember to check our documentation for comprehensive guides and examples.