Triggers

Triggers define which Paperless-ngx document events activate a rule.

Available triggers

Value	Description
`created`	Fires when a new document is added to Paperless-ngx.
`updated`	Fires when an existing document is modified.
`all`	Expands to both `created` and `updated`.

Usage

At least one trigger is required. all is the most common choice when a rule should apply regardless of whether the document is new or existing:

triggers:
  - all

Use individual values when you want finer control:

triggers:
  - created   # only on first ingestion

triggers:
  - created
  - updated   # equivalent to "all"

How triggers are matched

Paperless-ngx sends a document_added or document_updated event in the webhook payload. Secretary maps these to created and updated respectively.

When a rule has triggers: [all], the compiler expands it to [created, updated] internally — all is never stored in an event.

Batch runs via REST API or MQTT

When you trigger a rule via the REST API or MQTT without specifying an event type, Secretary defaults to updated. The trigger check is bypassed for manually initiated runs that explicitly target a single rule.