Appearance
Background Jobs
Many operations in TiruPay are too slow or too side-effect-heavy to run synchronously in a request — sending emails, generating PDF invoices, delivering webhooks, or processing payments. These are offloaded to a background job queue backed by Redis and RQ. The API returns immediately and the work happens asynchronously.
How Background Jobs Work
- A request triggers a job — the API enqueues the task with a unique
job_idand returns. - A worker picks it up — one of the background worker processes dequeues and executes the task.
- The result is stored — RQ keeps the job result in Redis for 120 minutes after completion.
- You can poll the status — use
GET /admin/jobs/to check what happened.
What Runs as a Background Job
| Area | Example tasks |
|---|---|
| Emails | Sending typed emails to customers |
| Webhooks | Delivering event payloads to registered URLs |
| PDF generation | Rendering invoice documents |
| Payments | Processing Mollie / Stripe / Nemo transactions |
| Images | Generating blurhash previews for uploaded files |
| Logging | Writing API call logs asynchronously |
In addition, TiruPay runs a set of scheduled (cron) jobs for recurring maintenance tasks such as deactivating expired subscriptions, billing pay-as-you-go balances, creating dunning reminders, and pruning old logs.
The BackgroundJob Object
| Field | Type | Description |
|---|---|---|
job_id | string | Unique identifier for this job |
func_name | string | Short name of the function that was executed |
state | BackgroundJobState | Current lifecycle state (see below) |
type | BackgroundJobRunResult | null | Outcome once the job has finished (see below) |
created_at | datetime | When the job was created |
enqueued_at | datetime | When the job entered the queue |
execution_started_at | datetime | When the worker began executing the job |
execution_ended_at | datetime | When execution completed |
Job States
| State | Description |
|---|---|
QUEUED | Enqueued, waiting for a worker |
RUNNING | A worker is currently executing the job |
FINISHED_RESULT_AVAILABLE | Completed; the result is still held in Redis |
FINISHED_CLEANED | Completed, but the result TTL (120 min) has expired |
UNKNOWN | State cannot be determined |
FINISHED_CLEANED is normal
Once more than 120 minutes have passed since a job finished, its result record is removed from Redis. The job itself is not lost — it was executed successfully — but TiruPay no longer has the outcome details. FINISHED_CLEANED simply means "ran and cleaned up."
Run Results
The type field is only set when the state is FINISHED_RESULT_AVAILABLE.
| Result | Description |
|---|---|
SUCCESSFUL | The job completed without errors |
FAILED | The job raised an exception |
STOPPED | The job was stopped externally |
RETRIED | The job was retried (intermediate state) |
MAX_RETRIED | The job exhausted all retry attempts |
Fetching Job Status
http
GET /admin/jobs/Returns a list of BackgroundJob objects.
Query parameters:
| Parameter | Required | Description |
|---|---|---|
service_id | Conditional | Filter by service. Required for non-SUPERADMIN roles. |
WARNING
Non-superadmin callers must provide a service_id that is within their permitted scope. Omitting it returns 400 Bad Request.
Example Response
json
[
{
"job_id": "3f4a1b2c-...",
"func_name": "_start_send_typed_email_as_background_task",
"state": "FINISHED_RESULT_AVAILABLE",
"type": "SUCCESSFUL",
"created_at": "2026-05-11T10:00:00Z",
"enqueued_at": "2026-05-11T10:00:00Z",
"execution_started_at": "2026-05-11T10:00:01Z",
"execution_ended_at": "2026-05-11T10:00:02Z"
},
{
"job_id": "9c8d7e6f-...",
"func_name": "_run_pdf_background_task",
"state": "QUEUED",
"type": null,
"created_at": "2026-05-11T10:01:00Z",
"enqueued_at": "2026-05-11T10:01:00Z",
"execution_started_at": null,
"execution_ended_at": null
}
]Retention and Limits
| Scope | Limit |
|---|---|
| Jobs tracked per service | Last 100 job IDs |
| Jobs tracked globally (SUPERADMIN view) | Last 5000 job IDs |
| Result data available after completion | 120 minutes |
| Default job execution timeout | 10 minutes |
INFO
Jobs older than the per-service or global list limits are simply no longer returned by the API. The job was still executed — it has just aged out of the tracking window.
Access Control
| Role | Can list jobs |
|---|---|
| User | - |
| Service | Own service (must provide service_id) |
| Admin | Own services (must provide service_id) |
| Superadmin | All jobs (omit service_id to see all) |
Relationships
- Emails — email delivery runs as a background job per recipient batch.
- Webhooks — every webhook delivery is dispatched as a background job.
- Invoicing — PDF generation is offloaded to a background job.
- Payments — payment processing against third-party providers runs asynchronously in a dedicated queue.
- Legal Documents — document finalization and scheduled publishing are handled by daily cron jobs.