Skip to content

Node · jobs

API platform

The product API did HTTP, long jobs, and inbound webhooks in one request cycle. Reports timed out, a failed webhook was gone, and one shared key could touch every resource. The request path is now Fastify. Slow work is a BullMQ job the client polls.

JOBS, WEBHOOKS, INVALIDATION, SCOPES

01Request and job

The handler validates the body, enqueues, and returns the job id. It does not call the report, the import, or the notification sender.

const job = await queue.add(name, payload, { jobId });
return { id: job.id, status: "queued" };

The status route reads that job. Completed, failed, and waiting are states the client can poll. A worker process shares the queue and does the work.

PathWaits for the work?
Create report, import, or notificationNo. Returns a job id
StatusNo. Reads the job record
Cheap reads and writesYes. They finish inside the request

02Webhooks

The public handler writes the payload and a received timestamp, then returns 200. A worker claims the row.

A downstream error schedules a retry with backoff. The sender already got 200, so it does not send the same delivery again. The retry that matters is ours.

StepWhat is true afterward
AcceptThe payload is stored. The sender can stop
ProcessA worker calls downstream. Failure schedules another attempt
ExhaustedThe row is failed. It is kept

03Cache

Redis holds aggregates that were too expensive to recompute on every read. The key is deleted on the write path that can change the number.

WriteKeys removed
Billing adjustmentThe account aggregate that includes that charge
Import commitThe list and count that the import feeds
Other writesNone. They do not touch a cached figure

04Keys

A key is a list of resources and a rate limit. The check runs before the handler.

CheckResult
Unknown key401
Known key, wrong resource403
Known key, over its limit429
Known key, in scope, under limitThe route runs

The previous credential was one secret in front of every route.