Webhook

The Paperless-ngx webhook is the primary entrypoint for Secretary. It receives document events from Paperless-ngx and triggers the rules engine.

Endpoint

POST /api/webhook/paperless

Authentication

If SECRETARY_API_TOKEN is set, every request must include a Bearer token in the Authorization header:

Authorization: Bearer <your SECRETARY_API_TOKEN>

If no token is configured, the endpoint is unauthenticated. It is strongly recommended to always set a token.

Setting up the webhook in Paperless-ngx

1. Open your Paperless-ngx instance and navigate to Administration → Workflows (or the Django admin panel at /admin/).
2. Create a new webhook trigger.
3. Set the URL to:

   http://<secretary-host>:7777/api/webhook/paperless
   

4. Add the header:
5. Key: Authorization
6. Value: Bearer <your SECRETARY_API_TOKEN>
7. Enable events: Document added and Document updated.

Payload format

Secretary accepts two payload formats emitted by different versions of Paperless-ngx.

Current format (document as object)

{
  "event": "document_added",
  "document": {
    "id": 42,
    "title": "Invoice 2024/01"
  }
}

Legacy format (document as URL)

{
  "event": "document_updated",
  "document": "http://paperless.example.com/api/documents/42/"
}

Both are accepted. The document ID is extracted from the URL automatically in the legacy case.

Supported event values

Response

On success, the endpoint returns HTTP 200 OK with an empty body. Rules are processed asynchronously — the webhook returns immediately and rule execution happens in the background.