Nextcloud Integration

[compgeniuses]

Hello, considering this works well with self hosting, i was wondering if you could consider adding a nextcloud integration, and a nextcloud app to the nextcloud app store.

1. Would give the project great visibility
2. Would be a wonderful sue case for signing documents on nextcloud

[JensUweB]

I would really love to see a Nextcloud App for this! Currently there is no viable open source alternative in Nextcloud. Those apps that do exist are either very hard to setup (looking at you, LibreSign) or don't have a free tier at all.

[compgeniuses]

https://github.com/geniusdynamics/ns8-docuseal

https://github.com/geniusdynamics/ns8-documenso

if you are looking for an easier way to self host the apps.
Hopefully we can also, build one for libresign, submit a feature request here https://community.nethserver.org/

[rvjr]

I was also exploring possible signing services with NC integration and ended up with DocuSeal. Having it integrated would be really cool, and especially the self hosting capabilities would nicely fit with an on premise NC...

[signebedi]

I would also love to see a nextcloud app for this. I have several use cases.

[xXRoxXeRXx]

Nextcloud integration analysis – blocked by Pro-only API

Following this discussion, I did a deep analysis of what it would take to build
a proper Nextcloud integration app for DocuSeal. Here's what I found.

What the integration would need

A meaningful Nextcloud integration requires being able to send a specific file
from NC Files to DocuSeal for signing – the core use case being:
right-click a PDF → select signers → send to DocuSeal → signed PDF comes back automatically.

For this, the integration needs to upload a file to DocuSeal via API.
The natural endpoint for this is POST /api/submissions/pdf.

The problem

Calling POST /api/submissions/pdf is an Pro-only feature

Question for the team

Would it be feasible to expose file upload (POST /api/submissions/pdf or
POST /api/templates/pdf) for self-hosted OSS instances?
The PDF processing library (hexapdf) is already part of the OSS codebase.
For self-hosted deployments – where users run their own infrastructure –
the API file upload restriction is the main blocker for any meaningful
third-party integration (Nextcloud, Seafile, ownCloud, etc.).

[cartenca73]

Deployed app in https://github.com/cartenca73/integration_docuseal

[miqmago]

In my case I've deployed a self-hosted instance and done integration with nextcloud (both are in same server)
I've completed setup but I was not sure of the name of the webhook secret key (I've placed X-Auth-Secret as I copied from API)
If I don't add the webhook secret (opzionalle) in nexcloud integration, it says "Error saving" with no logs etc... at the end I ended creating something that seems it could work and the settings got saved correctly.
I tried to restart nextcloud and also to do a file:scan --all but the feature does not appear on the right menu. I don't know what else to try.

Also the Signatures tab does not appear on lateral menu

seems the integration works as in docker logs of docuseal I can see aprox every 30s:

app-1  | I, [2026-05-05T16:48:42.320562 #1]  INFO -- : [bc9d4...] {"method":"GET","format":"html","controller":"WebhookSettingsController","action":"new","status":200,"allocations":6974,"duration":89.99,"view":7.49,"db":63.01,"host":"docuseal.example.com","fwd":"public.ip","params":{},"uid":1,"aid":1,"rid":null,"raid":null}

[cartenca73]

Hi, thanks for the detailed report. Three things:

1. Webhook header — use X-Docuseal-Signature, not X-Auth-Secret

X-Auth-Token is the API authentication header, that's a different mechanism. Webhook validation works like this:

In Nextcloud's "Webhook Secret" field: enter any random string (e.g. openssl rand -hex 32)
In DocuSeal → Settings → Webhooks → Secret: enter the same string
DocuSeal automatically computes an HMAC-SHA256 of the payload with that secret and sends it in the X-Docuseal-Signature header. The Nextcloud app verifies it.
You don't configure the header name anywhere — it's hardcoded on both sides. The only thing you and DocuSeal share is the secret string itself. The README isn't explicit about this; I'll update it.

2. "Error saving" with empty webhook secret

The webhook secret is genuinely optional and the frontend omits the field from the request when it's empty, so it shouldn't be what triggers the error. More likely cause: right after saving, the app tests the API connection, and if PHP can't reach your DocuSeal URL (self-signed cert, internal hostname, firewall, etc.) the request fails. Could you share:

Your Nextcloud version
Lines from data/nextcloud.log around the failed save (grep for integration_docuseal)
Whether curl -I -H "X-Auth-Token: YOUR_KEY" https://your-docuseal/api/templates works from the Nextcloud host
3. "Signatures" sidebar tab not appearing — confirmed bug in 1.1.10

This is a real bug, thanks for catching it. The sidebar JS bundle is built but never loaded by the app: lib/AppInfo/Application.php only registers the filesplugin script, not the sidebar one, so OCA.Files.Sidebar.registerTab(...) is never called. No amount of occ files:scan, restart, or cache clearing will help — the code path simply isn't wired up.

Workaround until I cut 1.1.11: edit lib/AppInfo/Application.php and add one line inside the LoadAdditionalScriptsEvent listener:

$eventDispatcher->addListener(LoadAdditionalScriptsEvent::class, function (): void {
Util::addScript(self::APP_ID, self::APP_ID . '-filesplugin');
Util::addScript(self::APP_ID, self::APP_ID . '-sidebar'); // <-- add this
Util::addStyle(self::APP_ID, 'files-style');
});
Then hard-refresh the browser (Ctrl+Shift+R) to bust the JS cache. The "Signatures" tab will then appear in the right sidebar for PDF and DOCX files.

Side note: if by "right menu" you actually meant the right-click context menu ("Request signature with DocuSeal"), that's a different bundle and should already be loading. It only shows up on PDF/DOCX/DOC/PNG/JPEG files though, so worth double-checking. Let me know which of the two you meant.

[miqmago]

Nextcloud Hub 25 Autumn
Docuseal integration: 1.1.10
Docuseal: 2.5.2 in docker compose:

services:
  app:
    image: docuseal/docuseal:latest
    ports:
      - "127.0.0.1:3999:3000"
    volumes:
      - ./docuseal:/data/docuseal
    environment:
      - DATABASE_URL=${DATABASE_URL}
    networks:
      - nextcloud_nextcloud_net

networks:
  nextcloud_nextcloud_net:
    external: true

I've added changes on lib/AppInfo/Application.php and now it appears the right tab but it's empty:

Context menu does not show any option regarding signature on Docuseal:

Also tried with an image:

The settings error was appearing only on first install, I couldn't reproduce again after first successful configuration.
On first install I had to fill the webhook secret otherwise the error was raising (something like "Error saving configuration").
Relevant Logs:

{"reqId":"5VwJ930sHapgCxiwxFxG","level":0,"time":"2026-05-05T15:35:35+00:00","remoteAddr":"my.ip","user":"--","app":"serverDI","method":"PUT","url":"/apps/integration_docuseal/config","message":"The requested alias \"OCP\\IServerContainer\" is deprecated. Please request \"Psr\\Container\\ContainerInterface\" directly. This alias will be removed in a future Nextcloud version.","userAgent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/147.0.0.0 Safari/537.36","version":"32.0.1.2","data":{"app":"serverDI"}}
{"reqId":"5VwJ930sHapgCxiwxFxG","level":0,"time":"2026-05-05T15:35:35+00:00","remoteAddr":"my.ip","user":"--","app":"onlyoffice","method":"PUT","url":"/apps/integration_docuseal/config","message":"The requested alias \"Request\" is deprecated. Please request \"OCP\\IRequest\" directly. This alias will be removed in a future Nextcloud version.","userAgent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/147.0.0.0 Safari/537.36","version":"32.0.1.2","data":{"app":"onlyoffice"}}
{"reqId":"5VwJ930sHapgCxiwxFxG","level":0,"time":"2026-05-05T15:35:36+00:00","remoteAddr":"my.ip","user":"myuser","app":"guests","method":"PUT","url":"/apps/integration_docuseal/config","message":"The requested alias \"OCP\\AppFramework\\IAppContainer\" is deprecated. Please request \"Psr\\Container\\ContainerInterface\" directly. This alias will be removed in a future Nextcloud version.","userAgent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/147.0.0.0 Safari/537.36","version":"32.0.1.2","data":{"app":"guests"}}
{"reqId":"L2CtPbUkNrk9q106o8w7","level":0,"time":"2026-05-05T15:35:37+00:00","remoteAddr":"my.ip","user":"myuser","app":"user_oidc","method":"PUT","url":"/apps/integration_docuseal/config","message":"The loading of lazy AppConfig values have been triggered by app \"user_oidc\"","userAgent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/147.0.0.0 Safari/537.36","version":"32.0.1.2","exception":{"Exception":"RuntimeException","Message":"The loading of lazy AppConfig values have been triggered by app \"user_oidc\"","Code":0,"Trace":[{"file":"/var/www/html/lib/private/AppConfig.php","line":492,"function":"loadConfig","class":"OC\\AppConfig","type":"->","args":["user_oidc",true]},{"file":"/var/www/html/lib/private/AppConfig.php","line":368,"function":"getTypedValue","class":"OC\\AppConfig","type":"->","args":["user_oidc","store_login_token","0",true,4]},{"file":"/var/www/html/custom_apps/user_oidc/lib/Service/TokenService.php","line":122,"function":"getValueString","class":"OC\\AppConfig","type":"->","args":["user_oidc","store_login_token","0",true]},{"file":"/var/www/html/custom_apps/user_oidc/lib/AppInfo/Application.php","line":92,"function":"checkLoginToken","class":"OCA\\UserOIDC\\Service\\TokenService","type":"->","args":[]},{"file":"/var/www/html/lib/private/AppFramework/Bootstrap/FunctionInjector.php","line":28,"function":"checkLoginToken","class":"OCA\\UserOIDC\\AppInfo\\Application","type":"->","args":[{"__class__":"OCA\\UserOIDC\\Service\\TokenService","clientService":{"__class__":"OCA\\UserOIDC\\Helper\\HttpClientHelper"}}]},{"file":"/var/www/html/lib/private/AppFramework/Bootstrap/BootContext.php","line":32,"function":"injectFn","class":"OC\\AppFramework\\Bootstrap\\FunctionInjector","type":"->","args":[{"__class__":"Closure"}]},{"file":"/var/www/html/custom_apps/user_oidc/lib/AppInfo/Application.php","line":77,"function":"injectFn","class":"OC\\AppFramework\\Bootstrap\\BootContext","type":"->","args":[{"__class__":"Closure"}]},{"file":"/var/www/html/lib/private/AppFramework/Bootstrap/Coordinator.php","line":170,"function":"boot","class":"OCA\\UserOIDC\\AppInfo\\Application","type":"->","args":[{"__class__":"OC\\AppFramework\\Bootstrap\\BootContext"}]},{"file":"/var/www/html/lib/private/App/AppManager.php","line":481,"function":"bootApp","class":"OC\\AppFramework\\Bootstrap\\Coordinator","type":"->","args":["user_oidc"]},{"file":"/var/www/html/lib/private/App/AppManager.php","line":273,"function":"loadApp","class":"OC\\App\\AppManager","type":"->","args":["user_oidc"]},{"file":"/var/www/html/lib/base.php","line":1013,"function":"loadApps","class":"OC\\App\\AppManager","type":"->","args":[["authentication"]]},{"file":"/var/www/html/index.php","line":25,"function":"handleRequest","class":"OC","type":"::","args":[]}],"File":"/var/www/html/lib/private/AppConfig.php","Line":1326,"message":"The loading of lazy AppConfig values have been triggered by app \"user_oidc\"","exception":{},"CustomMessage":"The loading of lazy AppConfig values have been triggered by app \"user_oidc\""}}
{"reqId":"2ajsqrT4XFt3E03FsUnW","level":2,"time":"2026-05-05T16:52:02+00:00","remoteAddr":"my.ip","user":"--","app":"integration_docuseal","method":"POST","url":"/apps/integration_docuseal/webhook","message":"DocuSeal webhook: invalid secret","userAgent":"DocuSeal.com Webhook","version":"32.0.1.2","data":{"app":"integration_docuseal"}}
{"reqId":"zKXnoIcsu1IyEzMeCURz","level":2,"time":"2026-05-06T14:37:44+00:00","remoteAddr":"my.ip","user":"--","app":"integration_docuseal","method":"POST","url":"/apps/integration_docuseal/webhook","message":"DocuSeal webhook: invalid secret","userAgent":"DocuSeal.com Webhook","version":"32.0.1.2","data":{"app":"integration_docuseal"}}

Now I've saved and the settings seems fine:

Yesterday I was trying with this secret: Ave2_w+rp!!o3456t3rge
I was getting "DocuSeal webhook: invalid secret" and in docuseal:

{
  "event_type": "template.created",
  "timestamp": "2026-05-06T14:26:07.111Z",
  "data": {
    "id": 2,
    "archived_at": null,
    "fields": [
      {
        "uuid": "a7df1e94-7fb4-4342-abae-95d0b1710ad4",
        "submitter_uuid": "b63eae16-062a-492b-b694-abeb6cd84c8e",
        "name": "",
        "type": "signature",
        "required": true,
        "areas": [
          {
            "x": 0.7275465745192308,
            "y": 0.7126337075671852,
            "w": 0.2265775240384615,
            "h": 0.1407244519094767,
            "attachment_uuid": "df8adced-c9c8-4479-b493-de66494de9e9",
            "page": 0
          }
        ]
      }
    ],
    "name": "Captura de pantalla 2026-05-06 a les 16.23.04",
    "preferences": {},
    "schema": [
      {
        "attachment_uuid": "df8adced-c9c8-4479-b493-de66494de9e9",
        "name": "Captura de pantalla 2026-05-06 a les 16.23.04"
      }
    ],
    "slug": "c61TpzMqfPYk4A",
    "source": "native",
    "submitters": [
      {
        "name": "Primera Parte",
        "uuid": "b63eae16-062a-492b-b694-abeb6cd84c8e"
      }
    ],
    "created_at": "2026-05-06T14:26:06.753Z",
    "updated_at": "2026-05-06T14:26:13.019Z",
    "author_id": 1,
    "external_id": null,
    "folder_id": 1,
    "shared_link": false,
    "application_key": null,
    "folder_name": "Default",
    "author": {
      "id": 1,
      "email": "myemail@example.com",
      "first_name": "xxxx",
      "last_name": "xxxxx"
    },
    "documents": [
      {
        "id": 15,
        "uuid": "df8adced-c9c8-4479-b493-de66494de9e9",
        "url": "https://docuseal.domain.com/file/WyIzZDdmMTJhOC1lMDUxLTQ3ZDEtOGNiMS1jM2Q5...--bbe10f74a7238d1050d914654a729b88ffa6c5aba7.../Captura%20de%20pantalla%202026-05-06%20a%20les%2016.23.04.png",
        "preview_image_url": "https://docuseal.domain.com/file/WyIxOWY0YTBkMC1hMzE3LTQ4Z...--591ffebb627aa25ec5999b051a754d59.../0.png",
        "filename": "Captura de pantalla 2026-05-06 a les 16.23.04.png"
      }
    ]
  }
}

Today I've changed to a openssl rand -hex 32 and it slightly changed in docuseal screen (now appears 401) but it still fails the communication:

{
  "event_type": "submission.created",
  "timestamp": "2026-05-06T14:26:22.034Z",
  "data": {
    "id": 2,
    "name": null,
    "slug": "tRVKW6Xjb745ef",
    "source": "invite",
    "submitters_order": "random",
    "expire_at": null,
    "created_at": "2026-05-06T14:26:21.928Z",
    "updated_at": "2026-05-06T14:26:21.928Z",
    "archived_at": null,
    "submitters": [
      {
        "id": 2,
        "slug": "m3LXWvSbHM6Gr5",
        "uuid": "b63eae16-062a-492b-b694-abeb6cd84c8e",
        "name": null,
        "email": "myemail@example.com",
        "phone": null,
        "completed_at": null,
        "declined_at": null,
        "external_id": null,
        "submission_id": 2,
        "metadata": {},
        "opened_at": null,
        "sent_at": "2026-05-06T14:26:21.924Z",
        "created_at": "2026-05-06T14:26:21.936Z",
        "updated_at": "2026-05-06T14:26:21.936Z",
        "status": "sent",
        "application_key": null,
        "values": [],
        "documents": [],
        "preferences": {
          "send_email": true
        },
        "role": "Primera Parte"
      }
    ],
    "template": {
      "id": 2,
      "name": "Captura de pantalla 2026-05-06 a les 16.23.04",
      "external_id": null,
      "created_at": "2026-05-06T14:26:06.753Z",
      "updated_at": "2026-05-06T14:26:13.019Z",
      "folder_name": "Default"
    },
    "created_by_user": {
      "id": 1,
      "email": "myemail@example.com",
      "first_name": "xxxx",
      "last_name": "xxxxx"
    },
    "variables": {},
    "submission_events": [
      {
        "id": 5,
        "submitter_id": 2,
        "event_type": "send_email",
        "event_timestamp": "2026-05-06T14:26:23.415Z",
        "data": {}
      }
    ],
    "documents": [],
    "audit_log_url": null,
    "combined_document_url": null,
    "status": "pending",
    "completed_at": null
  }
}

[miqmago]

@cartenca73 I've also seen that the sign side menú appears on pdf and docx:

---

but not in jpg/png:

---

Also checked the request and works fine:

root@cb83cdd699e1:/var/www/html# curl -I -H "X-Auth-Token: jST..." https://docuseal.instance.com/api/templates
HTTP/1.1 200 OK
Server: nginx/1.22.1
Date: Fri, 08 May 2026 15:02:34 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 0
Connection: keep-alive
x-frame-options: SAMEORIGIN
x-xss-protection: 0
x-content-type-options: nosniff
x-permitted-cross-domain-policies: none
referrer-policy: strict-origin-when-cross-origin
etag: W/"a21d8895cf8fbb4d..."
cache-control: max-age=0, private, must-revalidate
x-request-id: a5baf45d...
x-runtime: 0.017968
vary: Accept-Encoding

If you let me know how to debug I can help with more details (logs, etc...), just let me know

[cartenca73]

Hi,

Thanks for the very detailed report — the logs and screenshots made the root causes easy to pin down. I've just released v1.1.11 that addresses every single point you raised. Here's a breakdown of what was broken, what we changed, and how to configure it on your side.

1. Webhook returning "invalid secret" / 401 in DocuSeal
   Root cause. The previous version expected DocuSeal to send the secret as an HMAC-SHA256 signature in an X-Docuseal-Signature header. DocuSeal does not compute an HMAC by default — when you configure a "Webhook URL" in DocuSeal you also configure Custom Headers, and DocuSeal just sends those headers verbatim. That's why both your test secrets (Ave2_w+rp!!o3456t3rge and the openssl rand -hex 32 value) were rejected: the comparison never matched. The "401" you saw on the DocuSeal side is the unauthorized response we returned, telling DocuSeal to stop retrying.

What's fixed. The webhook validator now accepts the raw secret value in any of these header names:

X-Auth-Secret (this is the one we recommend)
X-Webhook-Secret
X-Webhook-Token
X-Docuseal-Secret
X-Docuseal-Signature (raw value, no HMAC)
Authorization: Bearer
?secret= query string
The HMAC-SHA256 path is still supported for users who proxy webhooks through a signer, but you don't need it.

How to configure it on your setup.

In Nextcloud: Settings → Connected accounts → DocuSeal, paste your secret (openssl rand -hex 32 is perfect) into Webhook Secret, click Save.
In DocuSeal: Settings → Webhooks → your webhook → Custom Headers add:
Name: X-Auth-Secret
Value: the exact same secret you saved in Nextcloud.
Trigger any event (create a template). In nextcloud.log you should now see DocuSeal webhook received: template.created instead of invalid secret.
If it still fails, the log line now also lists which credential headers were present — that tells you immediately whether the header name is wrong, the value is wrong, or the request never reached us.

2. "Error saving" on first install when leaving the webhook secret empty
   Root cause. The old setConfig endpoint chained the connection test to the save: if the DocuSeal server wasn't reachable yet (typical on first install, before the docker network is fully wired), the test result was reported as the save outcome and the admin UI displayed an error. The setting was actually persisted, but the feedback made it look like a failure.

What's fixed. The save and the connection probe are now decoupled:

Save always returns 200 with the new state.
The connection probe runs as best-effort and its result is reported separately. The frontend now shows "Configuration saved" even when the probe fails, and shows the failure message in a separate non-blocking banner.
We also added a manual Test connection button so you can re-check without having to re-save credentials.
The webhook secret field is genuinely optional now (it always was on the backend, but the previous flow made it feel mandatory).
3. Right-click action / "Sign with DocuSeal" missing in the file menu
Root cause. Two issues combined here:

The files plugin script was registered, but the asset bundling pipeline in the project was broken: npm run build failed in node_modules/axios and node_modules/webdav because of the stricter ESM resolution in webpack 5. The bundle that shipped with 1.1.10 was therefore stale or partial, depending on what was last built locally.
The sidebar script (sidebar.js) was never registered in Application.php at all — that's why your manual patch made the tab show up.
What's fixed.

webpack.config.js now applies node-polyfill-webpack-plugin and disables fullySpecified resolution for .js/.mjs files. A clean npm install --legacy-peer-deps && npm run build produces all three bundles without errors.
Application.php now registers both filesplugin and sidebar on the LoadAdditionalScriptsEvent, so you no longer need to patch it manually.
4. Sidebar tab appearing empty
Root cause. The sidebar component had an outer v-if="requests.length > 0 || loading" guard that hid the entire content when a file had no signature requests. That's why the tab appeared but rendered blank.

What's fixed. The component now always renders, with three states:

Loading spinner while fetching.
An empty-state message: "No signature requests for this file. Right-click and select 'Request signature with DocuSeal' to start."
An error state with a retry button if the API call fails (useful when DocuSeal isn't configured yet).
5. Right-click and sidebar not shown for PNG/JPG
Root cause. The sidebar tab's enabled() check only accepted application/pdf and the DOCX MIME type. The right-click action did include images, so the inconsistency was real.

What's fixed. Both the right-click action and the sidebar tab now accept the same set of MIME types: PDF, DOCX, DOC, PNG, JPEG (including the rarer image/jpg variant). They share a single SIGNABLE_MIMES definition so they can't drift apart again.

About the deprecation warnings in the log
The OCP\IServerContainer is deprecated, Request is deprecated, and OCP\AppFramework\IAppContainer is deprecated lines you pasted are emitted by the serverDI, onlyoffice, guests, and user_oidc apps — not by integration_docuseal. They appear on every request that traverses those apps' middleware, which includes the call to our config endpoint. Our code already uses the modern Psr\Container\ContainerInterface and OCP\IRequest directly, so there's nothing to fix on our side. The noise will go away when those other apps update.

Upgrading
cd /path/to/nextcloud/apps/integration_docuseal
git pull
npm install --legacy-peer-deps
npm run build
sudo -u www-data php occ upgrade
No database migration is required (no schema changes). On the first page load the admin panel will re-fetch the state from the server, so any "Error saving" toast you may still see from a cached page will disappear after a hard refresh.

Two final tips from your setup:

In your docker-compose.yml DocuSeal listens on 127.0.0.1:3999. Make sure the Nextcloud container/server can reach http://docuseal_app_hostname:3000 (the internal port, on the shared nextcloud_nextcloud_net network) — that's the URL to use in DocuSeal server URL, not localhost:3999 which is only resolvable from the host.
DocuSeal will keep retrying failed webhook deliveries for a while. After upgrading and reconfiguring X-Auth-Secret, you may see a flurry of successful webhook received log entries within a few minutes — those are the queued retries finally getting through. Nothing to worry about.
Let me know if anything is still off after the upgrade — and thanks again for the thorough write-up, it saved us a lot of guesswork.

Best,
Carlo Tenca

[cr00k]

is it known yet when newer version will be in the nextcloud store? Currently is still 1.1.10... which is broken and speaks only italian :)

Otherwise it's a great project and thanks.