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.
| Path | Waits for the work? |
|---|---|
| Create report, import, or notification | No. Returns a job id |
| Status | No. Reads the job record |
| Cheap reads and writes | Yes. 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.
| Step | What is true afterward |
|---|---|
| Accept | The payload is stored. The sender can stop |
| Process | A worker calls downstream. Failure schedules another attempt |
| Exhausted | The 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.
| Write | Keys removed |
|---|---|
| Billing adjustment | The account aggregate that includes that charge |
| Import commit | The list and count that the import feeds |
| Other writes | None. 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.
| Check | Result |
|---|---|
| Unknown key | 401 |
| Known key, wrong resource | 403 |
| Known key, over its limit | 429 |
| Known key, in scope, under limit | The route runs |
The previous credential was one secret in front of every route.