How to trigger Windmill script from nextcloud workflow

[ChrisEdgington]

We are running nextcloud AIO 31.0.8 self-hosted.

We want to trigger a Windmill script from the nextcloud workflow handlers so we can do things based on TAGs. For example, we want a windmill script to run when a TAG is added to a file:

However, its not clear that we can use a Windmill script in the nextcloud Windmill instance as the webhook. Is that possible?

If not, is there a way to configure the Windmill flow webhook handler to respond to tag events? I got it to get triggered on NodeWrittenEvent but I could not find an event that gets triggered on tagging.

I tried adding a webhook for the OCP\SystemTag\MapperEvent event - but it is not supported on our version of nextcloud. If we upgraded to the latest version - would this event be the one to use for being triggered on file tagging operations?

[tareko]

What you're proposing sounds very reasonable, and should be possible to do with Windmill/Flow/Nextcloud. I found the instructions incredibly confusing and unclear, so I fully understand the difficulties here.

The steps for this are found in the instructions, but I never found them cogent, so here's the best way I can explain them:

1. Windmill hooks into Nextcloud through a particular listener. The way this listener works is to create a webhook. This webhook runs when cron runs, generally every 5 minutes.

2. The webhook is created when you hit "deploy", and not when you hit "test run". If you watch your nextcloud.log, you can see if there's an error. For example, here is me trying to get a form submitted listener /webhook that didn't work:

{"reqId":"xx","level":3,"time":"2025-09-14T18:16:19+00:00","remoteAddr":"172.20.0.4","user":"--","app":"flow","method":"POST","url":"/ocs/v1.php/apps/app_api/api/v1/log?format=json","message":"Exception during registering webhook\nTraceback (most recent call last):\n  File \"/ex_app/lib/main.py\", line 493, in register_listener\n    r = NextcloudApp().webhooks.register(\n        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n  File \"/usr/local/lib/python3.12/site-packages/nc_py_api/webhooks.py\", line 116, in register\n    return WebhookInfo(self._session.ocs(\"POST\", f\"{self._ep_base}\", json=params))\n                       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n  File \"/usr/local/lib/python3.12/site-packages/nc_py_api/_session.py\", line 235, in ocs\n    raise NextcloudException(status_code=ocs_meta[\"statuscode\"], reason=ocs_meta[\"message\"], info=info)\nnc_py_api._exceptions.NextcloudException: [400] [\"OCA\\\\Forms\\\\Events\\\\FormSubmittedEvent\"] is not an event class compatible with webhooks <request: POST /ocs/v1.php/apps/webhook_listeners/api/v1/webhooks>\nStack (most recent call last):\n  File \"/usr/local/lib/python3.12/threading.py\", line 1032, in _bootstrap\n    self._bootstrap_inner()\n  File \"/usr/local/lib/python3.12/threading.py\", line 1075, in _bootstrap_inner\n    self.run()\n  File \"/usr/local/lib/python3.12/threading.py\", line 1012, in run\n    self._target(*self._args, **self._kwargs)\n  File \"/usr/local/lib/python3.12/concurrent/futures/thread.py\", line 93, in _worker\n    work_item.run()\n  File \"/usr/local/lib/python3.12/concurrent/futures/thread.py\", line 59, in run\n    result = self.fn(*self.args, **self.kwargs)\n  File \"/ex_app/lib/main.py\", line 358, in webhooks_syncing\n    _webhooks_syncing()\n  File \"/ex_app/lib/main.py\", line 394, in _webhooks_syncing\n    register_listener(event, expected_listener[\"filters\"], expected_listener[\"webhook\"], token)\n  File \"/ex_app/lib/main.py\", line 502, in register_listener\n    LOGGER.exception(\"Exception during registering webhook\", stack_info=True)","userAgent":"ExApp/flow/1.2.0 (httpx/0.28.1)","version":"31.0.8.1","data":{"app":"flow"}}

When it worked, I was able to get the following result for the command php ./occ webhook_listeners:list

+----+-------+--------+------------+----------------------------------------------------------+-------------------------------------+----------------------------------------+--------------+---------+------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| id | appId | userId | httpMethod | uri                                                      | event                               | eventFilter                            | userIdFilter | headers | authMethod | authData                                                                                                                                                                                                                                                                                             |
+----+-------+--------+------------+----------------------------------------------------------+-------------------------------------+----------------------------------------+--------------+---------+------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| 1  | flow  |        | POST       | /api/w/nextcloud/jobs/run/f/u/wapp_tloubani/dashing_flow | OCA\Forms\Events\FormSubmittedEvent | {"event.form.hash":"xxx"} |              |         | header     | xxx|xxx|3 |
+----+-------+--------+------------+----------------------------------------------------------+-------------------------------------+----------------------------------------+--------------+---------+------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

In order to make this happen, the first item is an action, not a trigger. I found out what to do at this webhook listener directory page.

The title of the block, as indicated in the Nextcloud Windmill guide, has to be CORE:LISTEN_TO_EVENT, exactly as you see it. In events, I put in OCA\Forms\Events\FormSubmittedEvent. In filters, I used the directory to figure out that the best way to filter was by hash in my case, so I put in {"event.form.hash": "myhash"}. When I hit deploy, that's when it created the listener as above.

This has been an incredibly painful process, and the very poor documentation is a big part of this. I see there are no open PRs in the repo to improve things, so if you're willing and able, please feel free to feedback what's useful from the above so I can try to add a PR to improve the documentation more.

[ChrisEdgington]

@tareko Thank you for the detailed response. I was able to get what you described working - the problem is that there seem to be no supported events for TAG operations. That's why I'm asking for a way to trigger a Windmill script from a nextcloud workflow which can be triggered by TAG operations on the filesystem.

[tareko]

The workflow uses the event / webhook system, so I would be surprised if it's not possible in windmill but possible in workflow. But I haven't done much with that, so I may well be off on that.

[oleksandr-nc]

Hello, if you are interested we have added TagAssignedEvent and TagUnassignedEvent to webhooks only recenetly for Nextcloud 32.

ref: nextcloud/server#54810

[ChrisEdgington]

Thank you for the info @oleksandr-nc - I am curious, regarding my original request, is there a way for us to use the NextCloud install of Windmill as a webhook endpoint - to trigger a script?

[tareko]

Thank you for the info @oleksandr-nc - I am curious, regarding my original request, is there a way for us to use the NextCloud install of Windmill as a webhook endpoint - to trigger a script?

I'm not sure if you figured this out, but reasonably sure the answer here is yes using the usual windmill mechanisms. If you have this sorted, please post. If not, then let me know and I'll see if I can figure it out and post instructions.

[ChrisEdgington]

I'm not sure if you figured this out, but reasonably sure the answer here is yes using the usual windmill mechanisms. If you have this sorted, please post. If not, then let me know and I'll see if I can figure it out and post instructions.

Nope, because the embedded Windmill instance is not providing the usual webhook trigger UI that shows you the endpoints for each script. Here is the windmill documentation that shows a screenshot of the UI where you can see the expected REST endpoint for triggering a script. https://www.windmill.dev/docs/core_concepts/webhooks

[reidellawfirm]

For those curious about the resolution to this, the webhooks are accessible and seem to work fine but they only appear after your script is deployed. Once the script is deployed, then the Details and Triggers tab is available in the Edit panel.