How TaskFlow Works

The complete job lifecycle — from enqueue to callback, retry, and dead-letter handling.

Register & Get Your API Key

One POST request to /api/auth/register returns your API key instantly. No dashboard, no OAuth dance.

curl -X POST https://taskflowq.com/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

# → {"api_key": "tfq_abc123...", "tier": "free"}

Enqueue a Job

POST a job with your task_url and payload. Optionally set priority (0–100), delay, and max retry attempts.

curl -X POST https://taskflowq.com/api/jobs \
  -H "X-API-Key: tfq_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "task_url": "https://yourapp.com/process",
    "payload": {"doc_id": "xyz"},
    "priority": 80,
    "max_tries": 5
  }'

# → {"job_id": "01JOB...", "status": "pending"}

Worker Picks Up & Delivers

Our BullMQ worker picks up the job and POSTs to your task_url with the payload and an HMAC-SHA256 signature in the X-TaskFlow-Signature header.

# POST sent to your task_url:
{
  "job_id": "01JOB...",
  "payload": {"doc_id": "xyz"},
  "attempt": 1
}

# Headers include:
X-TaskFlow-Signature: sha256=abc123...
X-TaskFlow-Job-Id: 01JOB...

Your Service Processes & Responds

Verify the HMAC signature, process the job, and return HTTP 200. Any non-2xx response is treated as a failure and triggers a retry.

# Python example — verify and process
import hmac, hashlib

def handle_task(request):
    sig = request.headers['X-TaskFlow-Signature']
    expected = 'sha256=' + hmac.new(
        SECRET.encode(), request.body, hashlib.sha256
    ).hexdigest()
    if not hmac.compare_digest(sig, expected):
        return 401  # Reject spoofed requests

    # Process your job...
    return 200  # Acknowledge success

Retry with Exponential Backoff

On failure, the job is retried using exponential backoff. Delay formula: min(2^attempt × 1000ms, 30s). After max_tries exhaustion, the job moves to the dead-letter queue.

# Retry schedule (max_tries: 5):
Attempt 1: immediate
Attempt 2: 2s delay
Attempt 3: 4s delay
Attempt 4: 8s delay
Attempt 5: 16s delay
→ After attempt 5: moves to dead-letter queue

# Check dead-letter jobs:
GET /api/jobs?status=dead_letter

Dead-Letter Queue & Manual Retry

Jobs that exhaust all retries land in the dead-letter queue. Inspect them, fix the underlying issue, and retry via the API — no data loss.

# Retry a dead-letter job
curl -X POST /api/jobs/01JOB.../retry \
  -H "X-API-Key: tfq_abc123"

# → {"job_id": "01JOB...", "status": "pending"}

🔒 HMAC Callback Security

Every callback is signed with a per-job HMAC-SHA256 secret generated at enqueue time. The secret is stored on the job record and never exposed in the API response — only used for signing. Always verify the X-TaskFlow-Signature header before processing to prevent spoofed callbacks.

Start Building →

Full API reference with request/response examples in the docs.