diff --git a/admin_manual/webhook_listeners/budibase_workflows.rst b/admin_manual/webhook_listeners/budibase_workflows.rst new file mode 100644 index 00000000000..b0c25b5fefa --- /dev/null +++ b/admin_manual/webhook_listeners/budibase_workflows.rst @@ -0,0 +1,39 @@ +================== +Budibase workflows +================== + + +Budibase can easily be connected to Nextcloud and start automations reacting to Nextcloud events. + + +Using a Nextcloud webhook as automation trigger +----------------------------------------------- + +When creating a new automation in Budibase, you can choose "Webhook" as trigger. + +.. image:: images/new_automation.png + :alt: Budibase for creating a new automation, with highlighted "Webhook" button + +Budibase shows a schema request URL you can use to send the expected payload schema in advance. + +The easiest way to to this is to go to the Orchestration Gateway admin settings and click "Register new Budibase webhook": + +.. image:: images/new_budibase.png + :alt: Orchestration Gateway dialog for registering a Budibase webhook + +Here you can fill in the event you want your automation to be started by and the schema URL, and then send the schema. Budibase will show 4 detected bindings upon successful sending. You can then fill in the trigger URL provided by Budibase, all needed filters and the authentication tokens that should be included in the callback, and save. +As soon as you have your automation deployed, it will now be triggered every time your chosen event happens in Nextcloud. + + + +Use payload information in bindings +----------------------------------- + +For every event, there are 4 bindings registered in Budibase: + +* ``user``: the user that triggered the Nextcloud event +* ``time``: a timestamp for the triggering +* ``event``: an array containing additional information about the event (see the :ref:`list of webhook events` for details) +* ``authentication``: the requested authentication tokens + +These bindings can be used in any step of your automation to use the information given by the callback. diff --git a/admin_manual/webhook_listeners/images/list_webhooks.png b/admin_manual/webhook_listeners/images/list_webhooks.png new file mode 100644 index 00000000000..8a1b2798478 Binary files /dev/null and b/admin_manual/webhook_listeners/images/list_webhooks.png differ diff --git a/admin_manual/webhook_listeners/images/new_automation.png b/admin_manual/webhook_listeners/images/new_automation.png new file mode 100644 index 00000000000..c769a4c0787 Binary files /dev/null and b/admin_manual/webhook_listeners/images/new_automation.png differ diff --git a/admin_manual/webhook_listeners/images/new_budibase.png b/admin_manual/webhook_listeners/images/new_budibase.png new file mode 100644 index 00000000000..59d19124c6b Binary files /dev/null and b/admin_manual/webhook_listeners/images/new_budibase.png differ diff --git a/admin_manual/webhook_listeners/images/new_webhook.png b/admin_manual/webhook_listeners/images/new_webhook.png new file mode 100644 index 00000000000..4f7efec4dd7 Binary files /dev/null and b/admin_manual/webhook_listeners/images/new_webhook.png differ diff --git a/admin_manual/webhook_listeners/index.rst b/admin_manual/webhook_listeners/index.rst index cc55c0dc25e..7fd55287ea1 100644 --- a/admin_manual/webhook_listeners/index.rst +++ b/admin_manual/webhook_listeners/index.rst @@ -36,17 +36,33 @@ Enable the ``webhook_listeners`` app that comes bundled with Nextcloud - e.g. occ app:enable webhook_listeners -Listening to events -------------------- +Managing webhooks +----------------- -You can use the OCS API to add webhooks for specific events. See: +You can either use the OCS API to manage your webhooks or install the additional ``orchestration_gateway`` app to have a graphical user interface for adding, changing and deleting webhooks. + +the Orchestration Gateway adds an administration settings page listing your registered webhooks and making it easy to configure them. + +.. image:: images/list_webhooks.png + :alt: Orchestration Gateway settings showing a list of registered webhooks + +To add a new one, you can choose between a generic new webhook or a Budibase-specific one. + + +.. image:: images/new_webhook.png + :alt: Orchestration Gateway dialog for adding a new webhook + + +If you want to use the OCS API to add webhooks for specific events, see: `Register a new webhook `_. -Note: When authenticating with the OCS API to register webhooks, the account you -use must have administrator rights or delegated administrator rights. +.. note:: + + When authenticating with the OCS API to register webhooks, the account you use must have administrator rights or delegated administrator rights. To delegate the webhook registration to non-admin users, they have to be in a group that gets administration privileges for "Webhooks" granted. To use the Orchestration Gateway UI, they need *additional* privileges for "Orchestration Gateway". -Listing registered webhooks -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Listing registered webhooks via occ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You can list all currently registered webhook listeners from the command line: @@ -203,6 +219,8 @@ The complete logs of the workers can be checked with (replace 1 with the worker It is recommended to restart this worker at least once a day to make sure code changes are effective and avoid memory leaks, in this example the service restarts every 60 seconds. +.. _webhook_events: + Nextcloud Webhook Events ------------------------ @@ -577,7 +595,104 @@ When the optional ``tables`` app is installed: "time": 1700054321, } + +Mail App Events +~~~~~~~~~~~~~~~~~ +Mail events use different distinct payload formats, depending on the event. +When the optional ``mail`` app is installed: + +- ``NewMessageReceivedEvent`` + +.. code-block:: json + + { + "event": { + "class": "OCA\\Mail\\Event\\NewMessageReceivedEvent", + "accountId": 34, + "inReplyToRfcMessageId": "5888857", + "mailboxId": 10, + "messageId": 108778, + "messageUri": "89789789", + "RfcMessageId": "897789", + "sentAt": "1787826765", + "subject": "Important data changes", + "threadRootId": "9947988" + }, + "user": { + "uid": "carol", + "displayName": "Carol" + }, + "time": 1787826832, + } + + +- ``MessageSentEvent`` + +.. code-block:: json + + { + "event": { + "class": "OCA\\Mail\\Event\\MessageSentEvent", + "accountId": 34, + "inReplyToRfcMessageId": "5888857", + "sendAt": "1787826765", + "subject": "Important data changes" + }, + "user": { + "uid": "carol", + "displayName": "Carol" + }, + "time": 1787826832, + } + + +- ``MessageFlaggedEvent`` + +.. code-block:: json + + { + "event": { + "class": "OCA\\Mail\\Event\\MessageFlaggedEvent", + "accountId": 34, + "flag": "Spam", + "mailboxId": 10, + "messageId": 108778, + "set": true, + "uid": 897789 + }, + "user": { + "uid": "carol", + "displayName": "Carol" + }, + "time": 1787826832, + } + + +- ``MessageDeletedEvent`` + +.. code-block:: json + + { + "event": { + "class": "OCA\\Mail\\Event\\MessageDeletedEvent", + "accountId": 34, + "mailboxId": 10, + "uid": 108778 + }, + "user": { + "uid": "carol", + "displayName": "Carol" + }, + "time": 1787826832, + } + .. note:: For filtering or automation, always check the actual payload you receive, as it matches the JSON examples above, not PHPDoc or internal PHP array type style. + + +.. toctree:: + :maxdepth: 2 + + budibase_workflows \ No newline at end of file diff --git a/go.php/index.html b/go.php/index.html index c85f4e03fb9..82d66a4d4b6 100644 --- a/go.php/index.html +++ b/go.php/index.html @@ -66,6 +66,7 @@

Redirecting to documentation...

'admin-windows-compatible-filenames': '/admin_manual/configuration_files/windows_compatible_filenames.html', 'admin-workflowengine': '/admin_manual/file_workflows/index.html', 'admin-android-deep-link-handling': '/admin_manual/configuration_server/android_deep_link_handling.html', + 'admin-webhook-listeners': 'admin_manual/webhook_listeners/index.html', 'developer-manual': '/developer_manual', 'developer-backports': '/developer_manual/getting_started/development_process.html#bugfixes',