Why should presentation generation be asynchronous?

Creating a presentation can involve content planning, document parsing, image work, layout, and file export. An asynchronous API returns a task identifier quickly and completes the expensive work outside the browser request. This avoids gateway timeouts and lets users leave and return without losing progress.

The asynchronous job model

Client → POST /presentations → local job: queued
                              ↓
                     provider async task
                              ↓
                 polling or verified webhook
                              ↓
                  completed / failed / timeout
                              ↓
                 authorized result retrieval

Your database is the source of truth for ownership, business state, and delivery. The provider task is an external dependency associated with that record.

Define explicit states

Use a state machine such as queued, submitted, running, completed, failed, timed_out, and review_required. Store timestamps and a safe error category. Do not overload one status with both provider progress and your business approval state.

Use bounded polling

• Poll from a worker, not directly from every open browser tab.
• Increase the interval gradually and add jitter.
• Stop after a documented deadline.
• Retry temporary transport failures without creating a new job.
• Do not retry validation or authentication errors unchanged.
• Reconcile jobs after worker restarts.

Polling is predictable and easy to debug. Its cost grows with job volume, which is why large systems often move to webhooks.

Process webhooks safely

A webhook endpoint should authenticate or verify the event, parse a small allowed payload, find the local job, and apply a state transition idempotently. Return quickly and do heavy work in a queue.

• Use HTTPS.
• Verify signatures, secrets, or documented authentication.
• Reject unexpected event types.
• Deduplicate using an event or task identifier.
• Handle delayed and out-of-order delivery.
• Never trust a result URL without matching it to the stored job.

Add a queue for capacity control

A queue separates user traffic from generation capacity. It can enforce per-tenant limits, global concurrency, priorities, scheduled work, and retry policies. A worker should lock one job, submit it once, persist the provider task ID, and release or reschedule the job safely.

Use a dead-letter or review queue for jobs that exceed retries. Silent infinite retry loops hide defects and waste credits.

Prevent duplicate presentations

Create a client request key from the business event—for example, account ID, reporting period, template version, and request type. Enforce uniqueness locally. If the provider request times out after it may have been accepted, reconcile before submitting again.

Keep tenant boundaries at every transition

Store the authenticated user or workspace with the local job. Check it when users create, view, cancel, edit, preview, or download. Provider task IDs are identifiers, not authorization tokens. Avoid exposing upstream errors or unrestricted result URLs.

Measure the pipeline