logo

Payload

A payload is the body of data attached to a task, message, or API request. In a task queue, the payload contains everything the worker needs to execute the job — IDs, parameters, configuration, or raw data.

Payload in Task Queues

When you create a task in AsyncQueue, the payload is a JSON object that gets forwarded to the callback URL:

await aq.tasks.create({
  targetUrl: 'https://your-app.com/api/resize-image',
  payload: {
    imageUrl: 'https://cdn.example.com/photo.jpg',
    width: 800,
    height: 600,
    format: 'webp',
  },
});

When AsyncQueue calls your endpoint, it sends this payload as the request body. Your handler reads the data and performs the work.

Best Practices

  • Keep payloads small: Store large data (files, blobs) in object storage and pass a URL in the payload instead
  • Include an idempotency key: Add a unique ID so your handler can detect and skip duplicate deliveries
  • Version your payloads: If your payload schema changes, include a version field so handlers can support both old and new formats during rollout
  • Avoid sensitive data: Don’t put raw credentials or personally identifiable information (PII) in payloads — pass a reference ID and look up sensitive data server-side

Example: Payload at Each Stage

// 1. Task created with payload
await aq.tasks.create({
  targetUrl: 'https://your-app.com/api/process',
  payload: { orderId: 'ord_123', action: 'generate-invoice' },
  webhookUrl: 'https://your-app.com/api/on-complete',
});


// 2. Callback receives the payload
app.post('/api/process', (req, res) => {
  const { orderId, action } = req.body; // the payload
  // ... do work
  res.json({ invoiceUrl: 'https://...' });
});


// 3. Webhook receives the result
app.post('/api/on-complete', (req, res) => {
  const result = req.body.result; // { invoiceUrl: '...' }
  res.status(200).json({ received: true });
});