Skip to content

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 ​

  1. A request triggers a job — the API enqueues the task with a unique job_id and returns.
  2. A worker picks it up — one of the background worker processes dequeues and executes the task.
  3. The result is stored — RQ keeps the job result in Redis for 120 minutes after completion.
  4. You can poll the status — use GET /admin/jobs/ to check what happened.

What Runs as a Background Job ​

AreaExample tasks
EmailsSending typed emails to customers
WebhooksDelivering event payloads to registered URLs
PDF generationRendering invoice documents
PaymentsProcessing Mollie / Stripe / Nemo transactions
ImagesGenerating blurhash previews for uploaded files
LoggingWriting 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 ​

FieldTypeDescription
job_idstringUnique identifier for this job
func_namestringShort name of the function that was executed
stateBackgroundJobStateCurrent lifecycle state (see below)
typeBackgroundJobRunResult | nullOutcome once the job has finished (see below)
created_atdatetimeWhen the job was created
enqueued_atdatetimeWhen the job entered the queue
execution_started_atdatetimeWhen the worker began executing the job
execution_ended_atdatetimeWhen execution completed

Job States ​

StateDescription
QUEUEDEnqueued, waiting for a worker
RUNNINGA worker is currently executing the job
FINISHED_RESULT_AVAILABLECompleted; the result is still held in Redis
FINISHED_CLEANEDCompleted, but the result TTL (120 min) has expired
UNKNOWNState 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.

ResultDescription
SUCCESSFULThe job completed without errors
FAILEDThe job raised an exception
STOPPEDThe job was stopped externally
RETRIEDThe job was retried (intermediate state)
MAX_RETRIEDThe job exhausted all retry attempts

Fetching Job Status ​

http
GET /admin/jobs/

Returns a list of BackgroundJob objects.

Query parameters:

ParameterRequiredDescription
service_idConditionalFilter 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 ​

ScopeLimit
Jobs tracked per serviceLast 100 job IDs
Jobs tracked globally (SUPERADMIN view)Last 5000 job IDs
Result data available after completion120 minutes
Default job execution timeout10 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 ​

RoleCan list jobs
User-
ServiceOwn service (must provide service_id)
AdminOwn services (must provide service_id)
SuperadminAll 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.