Some work should not hold an HTTP response open: image conversion, notification delivery, or a long report. A background worker can process it after the request commits. The hard boundary is ensuring that the business record and the instruction to perform follow-up work are not split by a crash. An outbox row written in the same database transaction as the record gives a worker a durable queue to poll. Workers can retry, so handlers must tolerate duplicate delivery and mark work complete only after its effect is safe. A queue is not a guarantee that external side effects happen exactly once.
Make this comfortable
Background Jobs and the Outbox Boundary
Working case
An inspection is saved and a reviewer notification is needed. If the service writes the inspection then crashes before publishing a message, the notification disappears. If it publishes first and later rolls back the inspection, the notification refers to a record that does not exist. The transaction sketch writes both the inspection and an outbox event. A worker reads pending events and sends the notification with a stable event ID. If delivery is uncertain, the downstream system needs its own deduplication or reconciliation rule.
Implementation
BEGIN;
INSERT INTO inspections (inspection_id, case_id, note)
VALUES (93, 47, 'seal replaced');
INSERT INTO outbox_events (event_id, event_type, record_id, state)
VALUES (581, 'inspection.created', 93, 'pending');
COMMIT;Cost and boundaries
Writing one outbox row adds one database write per business event and O(E) retained storage for E events until cleanup. Polling too often adds read load; polling too slowly delays delivery. Index pending rows and delete or archive completed work under a retention policy. The request can return promptly after the transaction, but the user-facing state must say 'queued' rather than 'delivered'. Monitor stuck events and retry counts; a silent backlog is a product failure even while API responses remain 201.
Common Mistakes
- Do not publish an external event before the business transaction commits.
- Do not promise exactly-once effects from an at-least-once worker.
- Do not display queued work as completed delivery.
Connected lessons
Backend and API Systems; Cursor Pagination for Changing Collections; Idempotent Write Requests and Lost Responses; Rate Limits and Request Budgets; HTTP requests: keep method, status, and body contracts separate; Form submission: validate on the server and return field errors; Routing: validate path parameters and return a stable error shape.
Failure trace
The API returns 201 after saving inspection 93, but the process crashes before publishing its notification. The record exists; the reviewer never hears about it. Publishing before commit merely reverses the problem. Put the event instruction in the same transaction as the record, then let a worker deliver it. The worker still needs an idempotent downstream action because a crash can happen after delivery but before acknowledging the outbox row.
Verification
- Crash after the transaction commits and verify the pending event remains available to a new worker.
- Deliver an event twice and confirm the recipient sees one effective notification.
- Pause the worker and alert on oldest pending event age rather than counting only API errors.
Decision note
An outbox narrows the database-to-queue gap; it does not guarantee exactly-once delivery to an external system. Report queued and delivered as different states so the interface matches reality.
Apply and check
Build Project: paginated inspection feed with safe writes; then check the boundary with Web Development: data and API contracts quiz.
Advanced connections
Signed Webhook Delivery and Replay Control.
Further connections
Accepted Operations and Status Resources.
Further connections
Push Delivery Retries, Expiry, and Inbox Fallback.
Further connections
Outbound Email and Delivery State; Email Intent, Outbox, and Idempotent Send.
Further connections
Background Workflow Reliability; Job Admission, Idempotency, and Status Resources.
web-tech
web-development