Nextcloud workflows with Windmill and webhooks

The event path has three hops, and each one is a place where you can filter, fail or leak data. A user action in Nextcloud, such as uploading a file, creating a share or moving a file into a folder, is picked up by the webhook listeners app. That app matches the action against the webhook rules an administrator has configured and posts a JSON payload to a Windmill endpoint. Windmill then runs the script or flow attached to that endpoint. If the flow needs to change anything in Nextcloud, such as writing a tag, adding a comment or moving a file, it calls back into Nextcloud's APIs using a workspace connection that holds its own credentials. Nothing in this chain runs inside Nextcloud's request cycle beyond the listener, so a slow or failed Windmill run does not block the user who triggered the event.

Where filtering happens. Filters can sit in three places: the webhook listeners app, the Windmill endpoint or the first step of the script. Filter as close to the source as the app allows. A rule in the listener that drops events for unrelated folders or file types means fewer payloads leave Nextcloud, fewer runs are billed or queued in Windmill, and less file metadata is sent to a system outside the Nextcloud server's trust boundary. Filters in Windmill are still useful as a second check, but they should not be the only control, because by then the payload has already left the source. Document which filter lives where, so an engineer changing one does not assume the other is absent.

Confirm the event types first. The set of events a webhook can subscribe to depends on the installed version of the webhook listeners app and on which Nextcloud apps emit events in your environment. Do not design the workflow from a list in documentation or a blog post. On a staging instance running the same Nextcloud and app versions as production, list the event types the app exposes in its admin interface or API, trigger each action you need, and record the payload fields that arrive. Check that the file path, owner, actor and folder identifiers you rely on are present in every payload you plan to use, because a missing field usually surfaces only as a failed run weeks later.

The return path needs its own controls. When Windmill calls back into Nextcloud, the workspace connection acts with the permissions of the account behind it. Create a dedicated service account, grant it access only to the folders the workflow touches, and make sure the connection can be rotated or revoked without editing every flow. Also plan for loops: a flow that writes a file can trigger another webhook event, so the listener rules and the script must agree on how to recognize and skip events the workflow itself caused.

Decisions to make before building. Decide which events justify a workflow at all, which filters belong in the listener, how the endpoint is authenticated, and which account the return path uses. Then test with one event type and one folder before expanding. Keep a short written record of the event types, payload fields and filters for each workflow, because the next Nextcloud or app upgrade is the most likely time for an event name or payload field to change.

Start by inventorying every automation that runs on the packaged Flow app, because the migration can only be scoped once you know what exists. For each flow, record the trigger (for example, a file being created or tagged in a given folder), each condition that filters it, and each action it performs, such as moving a file, applying a tag, sending a notification or calling an external service. Note the owner, the Nextcloud group or user account the flow runs under, and the folders or groups it touches. Export the flow definitions where your installed version allows it, and keep a copy of the configuration in your change records before you change anything. Once the inventory is complete, decide which flows can be rebuilt as Windmill scripts and which should be retired or redesigned. A flow that only reacts to a file event and writes back metadata is usually a good candidate, because the webhook listener can deliver the event and a script can perform the same write through the Nextcloud API. Flows that depend on logic the Flow app handled implicitly, such as retries, ordering or per-user permissions, need a written equivalent before they move. Mark any flow whose behavior your users rely on but nobody can explain, since those need review with the owner before rebuilding. Each decision should be recorded against the inventory line so auditors and operators can trace what replaced what. Use a parallel run to prove the replacement before the old automation is switched off. Build the Windmill version, point it at a test folder or a test group, and let both the old flow and the new script process the same sample documents. Compare the outputs, including file names, tags, moved locations, notifications and audit log entries. Keep the old automation disabled only after the new one produces matching results on test data across the cases you recorded, including the edge cases such as renamed files, duplicate events and documents that fail a condition. Disabling the old flow should be a separate, signed-off change, not a side effect of the rebuild. Confirm with the Nextcloud documentation what the deprecation of the Flow app means for your installed version and timeline. Check whether the app remains available, receives security fixes, or will be removed in a specific release, and whether it is compatible with the Nextcloud version you plan to run during and after the migration. Ask your Nextcloud support provider or DeployOpen to confirm the schedule against your upgrade plan, because a deprecation date that falls before your next upgrade changes the order of work. Plan for the old flows to keep running until the parallel run succeeds, and document any fallback if the Flow app stops working earlier than expected.

Test every document workflow in a staging Nextcloud instance that matches production in server version, installed apps, webhook listener configuration and OAuth workspace connection before any user relies on it. Build the plan from the events the workflow listens for. For each event type you use (upload, rename, move, share and delete) and each event filter you configured, run a known action and record three things: the exact payload Nextcloud sends, the run result Windmill reports, and the resulting state in Nextcloud. Compare payloads against the field list you documented, not against memory. A filter can match the right path and still deliver a field shape your script does not expect, so confirm the payload format against the webhook listeners version installed in staging.

Use a dedicated test folder populated with files whose names, contents and sizes you know in advance. Include a small text file, a file with spaces and non-ASCII characters in its name, a nested subfolder, and a large file close to the size your users actually handle. Write down the expected outcome for each step before you run it. Then test repeated events: resend the same event, or replay a captured payload, and confirm the workflow does not create duplicate documents, tags or notifications. Idempotency should come from the workflow design, such as checking a stored file identifier or processed marker before acting, so verify that the design does what the script claims. For large files, watch whether the event fires before the upload completes and whether Windmill times out or retries. For callback failure, stop the Windmill endpoint or make it return errors, then confirm that the failure is logged and that retried or queued work ends in a known state.

Agree on the rollback step before go-live. The safest stop is to disable the trigger or webhook registration for the affected filter, not to delete the workflow in Windmill. Disabling keeps the script, its version history and the OAuth workspace connection available for review and re-enablement. Write a short runbook that names who may disable a trigger, where the switch lives in Nextcloud and Windmill, and how to confirm that no new events are arriving afterward. Check that disabling one trigger does not revoke the OAuth connection that other flows depend on. Rehearse the rollback once in staging so the steps are proven before anyone needs them under pressure.

Finish with a written sign-off. Record test cases, payload samples, run results and the rollback rehearsal, and keep them with the workflow definition. Retest after every change to Nextcloud, the webhook listeners app or Windmill, because Nextcloud upgrades move one major version at a time and require third-party apps to be confirmed compatible first. If any workflow still depends on the deprecated packaged Flow app, plan its migration and test it under the same criteria. Ask your team to confirm which owner signs off on each workflow and how often the test set is rerun.