{
  "$type": "site.standard.document",
  "bskyPostRef": {
    "cid": "bafyreihqcall4v7myhikazubu2ioaxrwu5iadawm7abp7ty4e3z4qfooqa",
    "uri": "at://did:plc:5y2ps7xhcqmc2d63b73ui72s/app.bsky.feed.post/3miyurea5vma2"
  },
  "coverImage": {
    "$type": "blob",
    "ref": {
      "$link": "bafkreiat3ynth7eieah7j3fvf4i3d6jfjp63jsd6jumr5agea42qnsp5wq"
    },
    "mimeType": "image/png",
    "size": 2325926
  },
  "description": "Automate updates for your Paperless-ngx stack using Portainer webhooks and Home Assistant. This guide shows how to trigger container updates via REST commands for a fully hands-free, self-hosted document management system.",
  "path": "/automatically-update-paperless-ngx-with-a-webhook-portainer-home-assistant/",
  "publishedAt": "2026-04-08T18:00:50.000Z",
  "site": "https://blog.php-systems.com",
  "textContent": "# Why Automate Paperless-ngx Updates?\n\nIf you're running **Paperless-ngx** , keeping it up to date is essential.\n\nUpdates often include:\n\n  * Security patches\n  * OCR improvements\n  * Dependency updates\n  * Bug fixes\n\n\n\nBut manually updating Docker stacks can become tedious.\n\nBy combining:\n\n  * **Portainer**\n  * **Home Assistant**\n\n\n\nYou can create:\n\n> ✅ One-click updates\n> ✅ Scheduled updates\n> ✅ Fully automated maintenance\n> ✅ Remote trigger capability\n\n* * *\n\n# Architecture Overview\n\nHere’s the flow:\n\n`Home Assistant → REST Command → Portainer Webhook → Docker Stack Update → Paperless-ngx`\n\nThis means:\n\n  * Home Assistant triggers an HTTP request\n  * Portainer receives the webhook\n  * The stack redeploys\n  * Containers pull latest images\n\n\n\n* * *\n\n# Step 1: Enable Webhook in Portainer\n\nIn **Portainer** :\n\n  1. Go to your Paperless stack\n  2. Click **Editor**\n  3. Enable **Webhook**\n  4. Copy the generated webhook URL\n  5. (Re-)Deploy the stack - Otherwise the webhook will not be enabled.\n\n\n\nIt will look like:\n\n`https://portainer.local/api/webhooks/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`\n\n⚠ Keep this URL secret — it allows redeploying your stack.\n\n* * *\n\n# Step 2: Create a REST Command in Home Assistant\n\nIn your `configuration.yaml`:\n\n\n    rest_command:\n      update_paperless:\n        url: \"https://portainer.local/api/webhooks/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\"\n        method: POST\n\nThis creates a callable action inside **Home Assistant**.\n\n* * *\n\n# Step 3: Trigger the Update\n\nYou can now call it from:\n\n### Manual Service Call\n\n`service: rest_command.update_paperless`\n\n* * *\n\n### Automation Example\n\n\n    alias: Update Paperless Weekly\n    trigger:\n      - platform: time\n        at: \"03:00:00\"\n    condition: []\n    action:\n      - service: rest_command.update_paperless\n    mode: single\n\n* * *\n\n### A better Automation Example\n\n\n    alias: Paperless-NGX Updater\n    description: \"\"\n    triggers:\n      - type: turned_on\n        device_id: <your paperless ngx device>\n        entity_id: <your entity for the software update available>\n        domain: update\n        trigger: device\n        for:\n          hours: 0\n          minutes: 5\n          seconds: 0\n    conditions: []\n    actions:\n      - action: rest_command.update_paperless\n        metadata: {}\n        data: {}\n    mode: single\n\n* * *\n\n### Button in Dashboard\n\nAdd a simple Lovelace button:\n\n\n    type: button\n    name: Update Paperless\n    tap_action:\n      action: call-service\n      service: rest_command.update_paperless\n\n* * *\n\n# Step 4: What Happens Behind the Scenes\n\nWhen triggered:\n\n  1. Home Assistant sends POST request\n  2. Portainer webhook receives it\n  3. Stack redeploy begins\n  4. Docker pulls latest images\n  5. Containers restart\n\n\n\nYour **Paperless-ngx** instance is now updated.\n\n* * *\n\n# ⚠ Important Considerations\n\n## 1️⃣ Downtime\n\nDuring update:\n\n  * Containers restart\n  * UI may be temporarily unavailable\n\n\n\nSchedule updates during low usage times.\n\n* * *\n\n## 2️⃣ Backup Before Updating\n\nAlways back up:\n\n  * Database\n  * Media files\n  * Configuration\n\n\n\nThis is critical before automated updates.\n\n* * *\n\n## 3️⃣ Image Tags\n\nIf using:\n\n`image: paperless-ngx:latest`\n\nYou’ll always pull the newest version.\n\nFor stability, consider pinning versions instead.\n\n* * *\n\n# Security Best Practices\n\nBecause webhooks are powerful:\n\n  * Never expose Portainer publicly without protection\n  * Use a reverse proxy with authentication\n  * Restrict access via firewall\n  * Keep webhook URLs private\n\n\n\nOptional:\n\n  * Use an internal-only network\n  * Trigger via VPN access only\n\n\n\n* * *\n\n# Advanced Ideas\n\nOnce this is working, you can extend it:\n\n### 🔁 Conditional Updates\n\nOnly update if a new image exists.\n\n### 📊 Notifications\n\nSend a notification when update completes.\n\n### 🔍 Health Checks\n\nVerify Paperless is running after update.\n\n### 🔐 Authenticated Webhooks\n\nProxy webhook behind authentication layer.\n\n* * *\n\n# Infrastructure Recommendations\n\nAutomation-heavy setups benefit from reliable hardware:\n\n### 💾 NAS Storage\n\nFor Paperless document storage (Synology is popular)\n\n### 🔌 UPS Backup\n\nPrevent corruption during updates (APC units perform well)\n\n### 🖥 Low-Power Servers\n\nMini PCs (Intel N100) are ideal for Docker + Home Assistant\n\nThese align perfectly with self-hosting audiences and convert well.\n\n* * *\n\n# Common Mistakes to Avoid\n\n❌ Exposing webhook publicly\n❌ Not backing up before updates\n❌ Using unstable image tags blindly\n❌ Forgetting restart downtime\n❌ Hardcoding URLs incorrectly\n\n* * *\n\n# Final Thoughts\n\nBy combining:\n\n  * **Paperless-ngx**\n  * **Portainer**\n  * **Home Assistant**\n\n\n\nYou create a powerful, automated update pipeline for your self-hosted stack.\n\nNo more manual redeploys.\nNo more forgotten updates.\n\nJust clean, reliable automation.",
  "title": "🔄 Automatically Update Paperless-ngx with a Webhook (Portainer + Home Assistant)",
  "updatedAt": "2026-04-08T18:00:53.849Z"
}