Back to blog
HomelabAutomatizaciónSelf-hosting

Paperless-ngx 3.5.0 makes workflows and bulk tasks easier to use

Manual workflows and asynchronous bulk operations make Paperless-ngx easier to automate in a homelab.

By Isma5 min read

The bottleneck is not just OCR

Once a Paperless-ngx instance starts collecting a serious number of documents, scanning and OCR are only part of the job. Metadata still needs fixing, document states need changing, batches need tagging, and some rules only make sense after a human review. That is where library maintenance can turn into a slow session spent waiting for the interface.

Paperless-ngx 3.5.0 improves two useful parts of that process: it adds manual workflow triggers and moves bulk operations into asynchronous tasks. Together, those changes are relevant if Paperless is more than a place to drop PDFs. They separate document selection from the heavier work that happens afterwards.

Run a workflow when the review is done

A workflow no longer has to depend only on document intake, a document update, or a scheduled run. With a manual trigger, I can prepare a rule for a specific use case and run it after reviewing a selection. That is useful when a human decision should come before any metadata is changed.

For example, I can find unclassified invoices, verify that they belong to a particular supplier, and then run a workflow that assigns tags, a document type, a storage path, or custom fields. The point is not blind automation. It is avoiding the same edit repeated one document at a time.

Paperless-ngx runs workflow actions sequentially according to their order. Later assignment actions can replace earlier assignments, except for values that can contain multiple entries, such as tags, custom fields, and permissions, which are merged. That ordering is worth reviewing before running a workflow across a large selection.

Bulk work moves into the background

The other important change is that bulk operations are handed off asynchronously. In practical terms, the interface can submit work to the queue instead of waiting for the entire operation to finish before responding. That matters with larger document collections and on servers already busy consuming files, generating archive versions, or updating indexes.

This does not mean every operation will finish faster. The work still needs CPU, disk access, database capacity, and available workers. What changes is the user experience: a long-running action should not keep the page locked while Paperless handles every document.

In a homelab, this is a good reason to revisit queue capacity. Paperless uses a Redis-compatible broker for background work, and PAPERLESS_TASK_WORKERS controls how many tasks it can run in parallel. Raising that value without checking CPU usage is not automatically an improvement, especially when OCR is running too.

Let Laravel receive the event

Webhook actions allow a workflow to send a POST request to a chosen URL. The payload can be JSON or form data, it can use key-value pairs, and the workflow can include custom headers. Workflow titles and webhook payloads can also use Jinja templates.

That makes Laravel a sensible integration point. A small endpoint can receive the event, persist the minimum required data, push the actual work to its own queue, and decide what should happen next. It might synchronize another application, open a review task, finish a classification flow, or call the Paperless-ngx API later when needed.

The documented placeholders make it possible to send stable references instead of building a brittle integration around screen scraping. {{ doc_id }} identifies the document, {{ doc_title }} provides its current title, and {{ doc_url }} creates a link back to the Paperless interface when PAPERLESS_URL is configured. Correspondent, document type, dates, and custom fields can also be included.

Restrict where webhooks can go

If the Laravel webhook is exposed through HTTPS behind a reverse proxy, I would limit the destinations Paperless is allowed to contact. These are real Paperless-ngx settings and can be added to the environment of a Docker deployment. This example allows HTTPS webhooks over port 443 and blocks requests to internal addresses.

PAPERLESS_WEBHOOKS_ALLOWED_SCHEMES=https
PAPERLESS_WEBHOOKS_ALLOWED_PORTS=443
PAPERLESS_WEBHOOKS_ALLOW_INTERNAL_REQUESTS=false

This is not the right configuration by default if Laravel only exists on a private network. In that case, blocking internal requests prevents Paperless from reaching the service, so the endpoint must either be exposed through the proxy or internal destinations must be allowed deliberately. The goal is to avoid turning an overly powerful workflow into a way to reach local network resources.

The details that still matter

Manual workflows do not replace a classification strategy. Without clear filters, consistent tags, and a sensible action order, they simply offer a quicker way to apply mistakes to more documents. Before running a rule against a meaningful selection, I would test it with a handful of normal documents and edge cases.

Webhooks do not turn Paperless into a complete event bus either. The workflow sends an HTTP request, but Laravel still needs to protect the endpoint, log failures, handle duplicate deliveries, and move expensive work into a queue. A controller that performs everything during the request can recreate the blocking behavior this release helps remove from Paperless.

I would also check PAPERLESS_ALLOWED_HOSTS as part of the update. The release notes mention that some installations may need to adjust it, which is especially relevant for instances behind custom domains, reverse proxies, or multiple hostnames. It is a small configuration check that can prevent access errors unrelated to the workflow changes.

For me, the useful part is not only the manual button. It is the cleaner division of responsibilities: Paperless-ngx remains the document archive, while Laravel receives events and handles homelab-specific logic. The workflow becomes easier to maintain because neither tool has to pretend it owns the entire process.


Paperless-ngx v3.5.0 release notes Official workflow documentation

Newsletter

What I learn coding with AI, every two weeks in your inbox.

Real numbers, mistakes included. No spam, unsubscribe in one click.

No spam, unsubscribe in one click. I only use your email to send you this and the newsletter. More in the privacy policy.