Skip to main content

​
What is a job?

A job is a single HTTP request task: DispatchQ stores the request intent, makes the HTTP request to any URL (webhook, API endpoint, internal service, etc.), retries if needed, and stores the final result.

​
Lifecycle

pending -> active -> completed
pending -> active -> pending (retry)
pending -> active -> failed
pending -> cancelled
awaiting_approval -> pending -> active -> completed|failed

​
Job fields

​
id
string
required
Unique job ID (for example job_...).
​
status
string
required
Lifecycle status: pending, active, awaiting_approval, completed, failed, cancelled.
​
url
string
required
Target URL for the HTTP request.
​
method
string
required
HTTP method (GET|POST|PUT|PATCH|DELETE).
​
payload
object|null
JSON payload sent to the target URL.
​
headers
object|null
Optional per-job outbound headers.
​
queue
string
required
Queue name, default default.
​
dedupe_key
string|null
Deduplication key for semantic duplicates (24-hour window).
​
idempotency_key
string|null
Idempotency key from request header (24-hour window).
​
delay_until
datetime|null
Earliest time the job becomes eligible for delivery.
​
attempts
integer
required
Number of delivery attempts already used.
​
max_attempts
integer
required
Maximum delivery attempts before failed.
​
schedule_id
string|null
Populated when the job was created by a schedule.
​
callback_url
string|null
Optional URL notified on completion/failure.
​
actions
string[]
Allowed actions for current status (approve, cancel, retry).

​
Delay strings

Use delay with this format:
  • 30s
  • 5m
  • 1h
  • 1d
Anything outside ^(\d+)(s|m|h|d)$ is invalid.

​
Actions array

actions: ["cancel"]

​
Computed fields

​
retries_remaining
integer
Returned for retried pending/active jobs. Computed as max_attempts - attempts.
​
next_retry_in_seconds
integer
Seconds until next_retry_at when a retry is scheduled.