Allow internal Paperless webhook target

2026-05-08 00:09:13 +02:00
parent 58e737d5cd
commit bdd8501467
10 changed files with 40 additions and 4 deletions
--- a/.gitignore
+++ b/.gitignore
@@ -1,2 +1,3 @@
 node_modules/
 frontend/node_modules/
+frontend/dist/
--- a/README.md
+++ b/README.md
@@ -92,6 +92,7 @@ Für Portainer-Deployments ist `docker-compose.yml` als Git-basierter Stack vorb
 | `AUTH_TOKEN_EXPIRES_IN_HOURS` | `12` | Lebensdauer der Tokens. |
 | `PAPERLESS_BASE_URL` | *(leer)* | API-URL deiner paperless-ngx Instanz. |
 | `PAPERLESS_EXTERNAL_URL` | *(leer)* | Optionale externe URL für Direktlinks im Browser. |
+| `PAPERLESS_WEBHOOK_URL` | *(leer)* | Optionale Ziel-URL für den automatisch angelegten Paperless-Webhook. Sinnvoll für interne URLs wie `http://host:8112/integrations/paperless/webhook`, wenn der externe Proxy eingeschränkt ist. |
 | `APP_EXTERNAL_URL` | *(leer)* | Optionale externe URL der App (z. B. für Links im iCal-Feed), überschreibt den Host der eingehenden Anfrage. |
 | `APP_LOCALE` | `de` | Sprache für systemseitige Nachrichten (z. B. ntfy, E-Mail-Betreff); derzeit `de` oder `en`. |
 | `PAPERLESS_TOKEN` | *(leer)* | API-Token aus paperless-ngx. |
--- a/frontend/src/api/config.ts
+++ b/frontend/src/api/config.ts
@@ -6,6 +6,7 @@ export interface ServerConfig {
  databasePath: string;
  paperlessBaseUrl: string | null;
  paperlessExternalUrl: string | null;
+  paperlessWebhookUrl: string | null;
  appExternalUrl: string | null;
  appLocale: string;
  paperlessConfigured: boolean;
@@ -32,6 +33,7 @@ export interface SettingsResponse {
  values: {
    paperlessBaseUrl: string | null;
    paperlessExternalUrl: string | null;
+    paperlessWebhookUrl: string | null;
    appExternalUrl: string | null;
    appLocale: string;
    schedulerIntervalMinutes: number;
@@ -69,6 +71,7 @@ export interface SettingsResponse {
 export type UpdateSettingsPayload = Partial<{
  paperlessBaseUrl: string | null;
  paperlessExternalUrl: string | null;
+  paperlessWebhookUrl: string | null;
  appExternalUrl: string | null;
  appLocale: string;
  paperlessToken: string | null;
--- a/frontend/src/locales/de/common.json
+++ b/frontend/src/locales/de/common.json
@@ -203,12 +203,15 @@
    "webhookSetupRunning": "Konfiguriere Paperless…",
    "webhookSetupSuccess": "Paperless-Workflow konfiguriert (ID {{id}})",
    "webhookSetupError": "Paperless-Workflow konnte nicht konfiguriert werden",
-    "webhookSetupHelp": "Legt ein Secret an und erstellt oder aktualisiert in Paperless den Workflow \"Contract Companion AI Review\".",
+    "webhookSetupHelp": "Legt ein Secret an und erstellt oder aktualisiert in Paperless den Workflow \"Contract Companion AI Review\". Wenn eine Webhook-Ziel-URL gesetzt ist, nutzt Paperless diese URL.",
    "webhookWorkflowInfo": "Paperless-Workflow ID {{id}} ist verknüpft.",
    "ical": "iCal-Abo",
    "icalFeedUrl": "Feed-URL",
    "paperlessApiUrl": "Paperless API URL",
    "paperlessExternalUrl": "Paperless externe URL (für Direktlink)",
+    "paperlessWebhookUrl": "Paperless Webhook-Ziel-URL",
+    "paperlessWebhookUrlExample": "http://192.168.178.33:8112/integrations/paperless/webhook",
+    "paperlessWebhookUrlHelp": "URL, die Paperless beim Workflow aufruft. Nutze hier bevorzugt eine interne URL zur Backend-API, wenn der externe Proxy Zugriffsbeschränkungen hat.",
    "appExternalUrl": "Externe URL der App",
    "paperlessExample": "https://paperless.example.com",
    "appExternalExample": "https://contracts.example.com",
--- a/frontend/src/locales/en/common.json
+++ b/frontend/src/locales/en/common.json
@@ -203,12 +203,15 @@
    "webhookSetupRunning": "Configuring Paperless…",
    "webhookSetupSuccess": "Paperless workflow configured (ID {{id}})",
    "webhookSetupError": "Unable to configure Paperless workflow",
-    "webhookSetupHelp": "Creates a secret and creates or updates the Paperless workflow \"Contract Companion AI Review\".",
+    "webhookSetupHelp": "Creates a secret and creates or updates the Paperless workflow \"Contract Companion AI Review\". If a webhook target URL is set, Paperless uses that URL.",
    "webhookWorkflowInfo": "Paperless workflow ID {{id}} is linked.",
    "ical": "iCal subscription",
    "icalFeedUrl": "Feed URL",
    "paperlessApiUrl": "Paperless API URL",
    "paperlessExternalUrl": "Paperless external URL (for direct link)",
+    "paperlessWebhookUrl": "Paperless webhook target URL",
+    "paperlessWebhookUrlExample": "http://192.168.178.33:8112/integrations/paperless/webhook",
+    "paperlessWebhookUrlHelp": "URL called by the Paperless workflow. Prefer an internal backend API URL when the external proxy has access restrictions.",
    "appExternalUrl": "App external URL",
    "paperlessExample": "https://paperless.example.com",
    "appExternalExample": "https://contracts.example.com",
--- a/frontend/src/routes/Settings.tsx
+++ b/frontend/src/routes/Settings.tsx
@@ -59,6 +59,7 @@ interface HealthResponse {
 type FormValues = {
  paperlessBaseUrl: string;
  paperlessExternalUrl: string;
+  paperlessWebhookUrl: string;
  appExternalUrl: string;
  appLocale: string;
  paperlessToken: string;
@@ -91,6 +92,7 @@ type FormValues = {
 const defaultValues: FormValues = {
  paperlessBaseUrl: "",
  paperlessExternalUrl: "",
+  paperlessWebhookUrl: "",
  appExternalUrl: "",
  appLocale: "de",
  paperlessToken: "",
@@ -187,6 +189,7 @@ export default function SettingsPage() {
    const values: FormValues = {
      paperlessBaseUrl: settingsData.values.paperlessBaseUrl ?? "",
      paperlessExternalUrl: settingsData.values.paperlessExternalUrl ?? "",
+      paperlessWebhookUrl: settingsData.values.paperlessWebhookUrl ?? "",
      appExternalUrl: settingsData.values.appExternalUrl ?? "",
      appLocale: settingsData.values.appLocale ?? "de",
      paperlessToken: "",
@@ -354,6 +357,9 @@ export default function SettingsPage() {
    if (formValues.paperlessExternalUrl !== initial.paperlessExternalUrl) {
      payload.paperlessExternalUrl = trimOrNull(formValues.paperlessExternalUrl);
    }
+    if (formValues.paperlessWebhookUrl !== initial.paperlessWebhookUrl) {
+      payload.paperlessWebhookUrl = trimOrNull(formValues.paperlessWebhookUrl);
+    }
    if (formValues.appExternalUrl !== initial.appExternalUrl) {
      payload.appExternalUrl = trimOrNull(formValues.appExternalUrl);
    }
@@ -707,6 +713,13 @@ export default function SettingsPage() {
                    placeholder={t("settings.paperlessExample")}
                    fullWidth
                  />
+                  <TextField
+                    label={t("settings.paperlessWebhookUrl")}
+                    {...register("paperlessWebhookUrl")}
+                    placeholder={t("settings.paperlessWebhookUrlExample")}
+                    fullWidth
+                    helperText={t("settings.paperlessWebhookUrlHelp")}
+                  />
                  <TextField
                    label={t("settings.appExternalUrl")}
                    {...register("appExternalUrl")}
--- a/src/config.ts
+++ b/src/config.ts
@@ -9,6 +9,7 @@ const configSchema = z.object({
  paperlessBaseUrl: z.string().url().optional(),
  paperlessToken: z.string().min(1).optional(),
  paperlessExternalUrl: z.string().url().optional(),
+  paperlessWebhookUrl: z.string().url().optional(),
  appExternalUrl: z.string().url().optional(),
  appLocale: z.enum(supportedLocales).default("de"),
  schedulerIntervalMinutes: z.coerce.number().min(5).default(60),
@@ -62,6 +63,7 @@ const rawConfig = {
  paperlessBaseUrl: readEnv("PAPERLESS_BASE_URL"),
  paperlessToken: readEnv("PAPERLESS_TOKEN"),
  paperlessExternalUrl: readEnv("PAPERLESS_EXTERNAL_URL"),
+  paperlessWebhookUrl: readEnv("PAPERLESS_WEBHOOK_URL"),
  appExternalUrl: readEnv("APP_EXTERNAL_URL"),
  appLocale: readEnv("APP_LOCALE"),
  schedulerIntervalMinutes: readEnv("SCHEDULER_INTERVAL_MINUTES"),
--- a/src/index.ts
+++ b/src/index.ts
@@ -90,6 +90,7 @@ const loginSchema = z.object({
 const settingsUpdateSchema = z.object({
  paperlessBaseUrl: z.string().url().nullable().optional(),
  paperlessExternalUrl: z.string().url().nullable().optional(),
+  paperlessWebhookUrl: z.string().url().nullable().optional(),
  appExternalUrl: z.string().url().nullable().optional(),
  appLocale: z.enum(["de", "en"]).optional(),
  paperlessToken: z.string().min(1).nullable().optional(),
@@ -129,6 +130,7 @@ function formatSettingsResponse(runtime: RuntimeSettings) {
    values: {
      paperlessBaseUrl: runtime.paperlessBaseUrl,
      paperlessExternalUrl: runtime.paperlessExternalUrl,
+      paperlessWebhookUrl: runtime.paperlessWebhookUrl,
      appExternalUrl: runtime.appExternalUrl,
      appLocale: runtime.appLocale,
      schedulerIntervalMinutes: runtime.schedulerIntervalMinutes,
@@ -393,6 +395,7 @@ app.get("/config", (_req, res) => {
    databasePath: config.databasePath,
    paperlessBaseUrl: runtime.paperlessBaseUrl,
    paperlessExternalUrl: runtime.paperlessExternalUrl,
+    paperlessWebhookUrl: runtime.paperlessWebhookUrl,
    appExternalUrl: runtime.appExternalUrl,
    appLocale: runtime.appLocale,
    paperlessConfigured,
@@ -431,6 +434,9 @@ app.put("/settings", (req, res) => {
  if (Object.prototype.hasOwnProperty.call(payload, "paperlessExternalUrl")) {
    update.paperlessExternalUrl = payload.paperlessExternalUrl ?? null;
  }
+  if (Object.prototype.hasOwnProperty.call(payload, "paperlessWebhookUrl")) {
+    update.paperlessWebhookUrl = payload.paperlessWebhookUrl ?? null;
+  }
  if (Object.prototype.hasOwnProperty.call(payload, "appExternalUrl")) {
    update.appExternalUrl = payload.appExternalUrl ?? null;
  }
@@ -542,8 +548,9 @@ app.post("/settings/paperless-webhook/setup", async (req, res, next) => {
    }

    const secret = runtime.paperlessWebhookSecret ?? generateSecret(32);
-    const appUrl = resolveAppBaseUrl(req, runtime);
-    const webhookUrl = `${appUrl}/api/integrations/paperless/webhook`;
+    const webhookUrl = runtime.paperlessWebhookUrl
+      ? runtime.paperlessWebhookUrl.replace(/\/$/, "")
+      : `${resolveAppBaseUrl(req, runtime)}/api/integrations/paperless/webhook`;
    const workflow = await paperlessClient.upsertContractCompanionWorkflow(webhookUrl, secret);
    const workflowId = typeof workflow.id === "number" ? workflow.id : null;
    const updated = updateRuntimeSettings({
--- a/src/runtimeSettings.ts
+++ b/src/runtimeSettings.ts
@@ -12,6 +12,7 @@ import {
 export interface RuntimeSettings {
  paperlessBaseUrl: string | null;
  paperlessExternalUrl: string | null;
+  paperlessWebhookUrl: string | null;
  appExternalUrl: string | null;
  appLocale: string;
  paperlessToken: string | null;
@@ -123,6 +124,7 @@ export function getRuntimeSettings(): RuntimeSettings {
  return {
    paperlessBaseUrl: coerceString(stored.paperlessBaseUrl, config.paperlessBaseUrl ?? null),
    paperlessExternalUrl: coerceString(stored.paperlessExternalUrl, config.paperlessExternalUrl ?? null),
+    paperlessWebhookUrl: coerceString(stored.paperlessWebhookUrl, config.paperlessWebhookUrl ?? null),
    appExternalUrl: coerceString(stored.appExternalUrl, config.appExternalUrl ?? null),
    appLocale: normalizeLocale(stored.appLocale, config.appLocale),
    paperlessToken: coerceString(stored.paperlessToken, config.paperlessToken ?? null),
--- a/src/settingsStore.ts
+++ b/src/settingsStore.ts
@@ -10,6 +10,7 @@ const listStmt = db.prepare("SELECT key, value FROM settings");
 export type SettingKey =
  | "paperlessBaseUrl"
  | "paperlessExternalUrl"
+  | "paperlessWebhookUrl"
  | "appExternalUrl"
  | "appLocale"
  | "paperlessToken"