native triggers (#1253)

* feat: add native triggers documentation (Nextcloud, Google Drive, Google Calendar)

Add documentation for native triggers, a new Enterprise feature that allows
Nextcloud, Google Drive, and Google Calendar to push events to Windmill.

Ref: windmill-labs/windmill#7837

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* improve

---------

Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: hugocasa <hugo@casademont.ch>

Author: 4 people

changelog/2026-02-16-native-triggers/index.md

@@ -0,0 +1,15 @@
+---
+slug: native-triggers
+title: Native triggers
+version: v1.636.0
+tags: ['Triggers', 'Nextcloud', 'Google']
+description: Trigger scripts and flows in real-time from Nextcloud, Google Drive, and Google Calendar events via push notifications.
+features:
+  [
+    'Nextcloud: file, folder, and calendar event triggers.',
+    'Google Drive: watch a specific file or all changes.',
+    'Google Calendar: track event creation, updates, and deletions.'
+  ]
+docs: /docs/core_concepts/native_triggers
+image: ./native_triggers.png
+---

changelog/2026-02-16-native-triggers/native_triggers.png

@@ -0,0 +1,162 @@
+---
+description: How do I trigger scripts and flows from Nextcloud or Google Drive/Calendar events in Windmill?
+---
+
+import DocCard from '@site/src/components/DocCard';
+
+# Native triggers
+
+Native triggers allow external services to push events directly to Windmill and trigger [scripts](../../script_editor/index.mdx) and [flows](../../flows/1_flow_editor.mdx). Unlike [scheduled polls](../../flows/10_flow_trigger.mdx), native triggers receive real-time push notifications from the external service via webhooks, so your runnables execute as soon as events occur.
+
+Currently supported services:
+
+- [Nextcloud](#nextcloud-triggers) - file, folder, and calendar change events
+- [Google](#google-triggers) - drive and calendar change events
+
+---
+
+## How it works
+
+Native triggers use [OAuth](../../misc/2_setup_oauth/index.mdx) to authenticate with the external service. Each trigger registers a webhook or watch channel on the external service, which sends notifications to Windmill when events occur. Windmill then executes the configured script or flow with the event data.
+
+The general setup follows two steps:
+
+1. **Connect the service** via workspace settings (OAuth authentication)
+2. **Create a trigger** on a script or flow, selecting the service and configuring which events to watch
+
+---
+
+## Setup
+
+### Workspace integration
+
+Before creating native triggers, you need to connect the external service in your workspace settings.
+
+1. Go to **Workspace settings** > **Integrations** > **Native triggers**
+2. Click **Connect** on the service you want to use (Nextcloud or Google)
+3. Provide the [OAuth](../../misc/2_setup_oauth/index.mdx) credentials (client ID and client secret)
+4. Complete the OAuth authorization flow
+5. Choose a [resource](../3_resources_and_types/index.mdx) path where the connection will be stored in the workspace
+
+![Workspace integration](./workspace_integration.png "Workspace settings showing native triggers integrations for Nextcloud and Google")
+
+The integration creates a [resource](../3_resources_and_types/index.mdx) in your workspace at the path you specify. The OAuth token is refreshed automatically, so you don't need to re-authenticate manually. You can use this resource in your scripts to query the service API with the same credentials used by the trigger.
+
+For Google integrations, the created [resource](../3_resources_and_types/index.mdx) is of type `gworkspace`. The OAuth scopes used are:
+- `https://www.googleapis.com/auth/drive.readonly`
+- `https://www.googleapis.com/auth/calendar.readonly`
+- `https://www.googleapis.com/auth/calendar.events`
+
+If you need additional scopes (e.g. write access), set up a separate resource with the desired scopes.
+
+A superadmin can share [instance-level](../../advanced/18_instance_settings/index.mdx) Google workspace settings so that workspace admins can connect Google native triggers without configuring their own OAuth client.
+The credentials are not exposed to workspace admins.
+
+![Instance gworkspace settings](./instance_gworkspace.png "Instance-level gworkspace settings with shared credentials toggle and redirect URI")
+
+For Nextcloud, you also need to provide the base URL of your Nextcloud instance.
+
+### Create a trigger
+
+Once the workspace integration is configured:
+
+1. Go to **Nextcloud** or **Google** tab (only visible once the corresponding [workspace integration](#workspace-integration) is configured)
+2. Click **New trigger**
+3. Select the script or flow to trigger
+4. Configure the service-specific options (see sections below)
+5. Save the trigger
+
+You can also create native triggers directly from a script or flow's **Triggers** tab.
+
+---
+
+## Nextcloud triggers
+
+Nextcloud native triggers watch for file, folder, and calendar changes on a [Nextcloud](https://nextcloud.com/) instance and trigger a script or flow when events occur.
+
+### Prerequisites
+
+- Nextcloud 33 or later
+- The [Windmill integration app](https://apps.nextcloud.com/apps/integration_windmill) installed on your Nextcloud instance
+- [Pretty URLs](https://docs.nextcloud.com/server/latest/admin_manual/installation/source_installation.html#pretty-urls) enabled on your Nextcloud instance
+
+### Configuration
+
+When creating a Nextcloud trigger, pick a script or flow (or use **Create from template**), then configure:
+
+- **Event** - select the event type to listen for. Available events include:
+  - Calendar events: object created, moved, trashed, restored, or changed in a Nextcloud calendar
+  - File/folder events: node created, changed, or written
+
+![Nextcloud trigger configuration](./nextcloud_trigger.png "Nextcloud trigger creation with event type selection")
+
+### Event payload
+
+Nextcloud sends the full event data to your script. The payload includes the authenticated user, a timestamp, and the event details:
+
+```typescript
+export async function main(
+  authentication: {
+    owner: RT.Nextcloud;
+    trigger: RT.Nextcloud;
+  },
+  user: {
+    uid: string;
+    displayName: string;
+  },
+  time: number,
+  event: any
+) {
+  // event contains the Nextcloud event details (file, folder, or calendar object)
+}
+```
+
+---
+
+## Google triggers
+
+Google native triggers watch for changes in [Google Drive](https://drive.google.com/) or [Google Calendar](https://calendar.google.com/) and trigger a script or flow when events occur.
+
+### Prerequisites
+
+- A Google Cloud project with the relevant API enabled ([Drive API](https://developers.google.com/drive/api), [Calendar API](https://developers.google.com/calendar/api), or both)
+- [OAuth 2.0](https://console.cloud.google.com/apis/credentials) credentials (client ID and client secret) configured with the appropriate scopes
+
+### Configuration
+
+When creating a Google trigger, pick a script or flow (or use **Create from template**), then configure:
+
+- **Trigger Type** - choose between **Drive** and **Calendar**
+- **Watch Mode** (Drive only) - choose between:
+  - **Specific file** - watch a single file or folder from My Drive, Shared with me, or Shared drives
+  - **All changes** - watch all changes across your Google Drive (fires whenever any file is created, modified, or deleted)
+- **Calendar** (Calendar only) - select a calendar from your Google account to watch for event changes
+
+![Google trigger configuration](./google_trigger.png "Google trigger creation with trigger type and watch mode selection")
+
+Both use push notifications via Google watch channels. Windmill automatically renews channels before they expire. The expiration period differs by service: 24 hours for Drive, 7 days for Calendar.
+
+### Event payload
+
+Google push notifications only contain metadata about the change, not the full event details. To get the actual content of the change, use the [`gworkspace` resource](../3_resources_and_types/index.mdx) created during workspace integration to query the Google API.
+
+```typescript
+type GoogleTriggerPayload = {
+  channel_id: string;
+  resource_id: string;
+  resource_state: string; // "sync" | "exists" | "not_exists" | "update"
+  resource_uri: string;
+  message_number: string;
+  channel_expiration: string;
+  channel_token: string; // custom token set when creating the watch
+  changed: string; // Drive-only: comma-separated list (e.g. "content,properties,permissions")
+};
+
+export async function main(payload: GoogleTriggerPayload) {
+  // Use the gworkspace resource to query the Google API for full details
+}
+```
+
+Use the [Google native trigger template script](https://hub.windmill.dev/scripts/gworkspace/22221/google-native-trigger-template-script-gworkspace) (also available from the UI when creating a trigger) as a starting point.
+
+---

docs/core_concepts/52_native_triggers/google_trigger.png

@@ -71,6 +71,11 @@ On top of its editors to build endpoints, flows, [low-code apps](../apps/0_app_e
 		description="Trigger scripts and flows from Google Cloud Pub/Sub messages."
 		href="/docs/core_concepts/gcp_triggers"
 	/>
+	<DocCard
+		title="Native triggers"
+		description="Trigger scripts and flows from Nextcloud, Google Drive, and Google Calendar events."
+		href="/docs/core_concepts/native_triggers"
+	/>
 </div>
 
 ## Windmill features

docs/core_concepts/52_native_triggers/index.mdx

@@ -31,6 +31,7 @@ Triggers from external events:
 - [SQS triggers](#sqs-triggers)
 - [MQTT triggers](#mqtt-triggers)
 - [GCP triggers](#gcp-triggers)
+- [Native triggers](#native-triggers) (Nextcloud, Google Drive, Google Calendar)
 - [Scheduled polls](#scheduled-polls-scheduling--trigger-scripts)
 
 :::info Scripts and Flows in Windmill
@@ -364,6 +365,18 @@ Windmill can connect to Google Cloud Pub/Sub, subscribe to specific topics, and
 </div>
 
 
+### Native triggers
+
+Native triggers allow external services like Nextcloud, Google Drive, and Google Calendar to push events directly to Windmill, triggering scripts or flows in real-time via webhooks or watch channels.
+
+<div className="grid grid-cols-2 gap-6 mb-4">
+  <DocCard
+    title="Native triggers"
+    description="Trigger scripts and flows from Nextcloud, Google Drive, and Google Calendar events."
+    href="/docs/core_concepts/native_triggers"
+  />
+</div>
+
 ### Scheduled polls (Scheduling + Trigger scripts)
 
 A particular use case for schedules are [Trigger scripts](../../flows/10_flow_trigger.mdx).

docs/core_concepts/52_native_triggers/instance_gworkspace.png

@@ -38,6 +38,10 @@ Your resource can be used [passed as parameters](../core_concepts/3_resources_an
 > Example of a Supabase resource being used in two different manners from a script in Windmill.
 <br/>
 
+## Native triggers
+
+You can use [native triggers](../core_concepts/52_native_triggers/index.mdx) to automatically run scripts or flows when calendar events are created, updated, or deleted. Native triggers receive real-time push notifications so your runnables execute as soon as events occur.
+
 :::tip
 
 Find some pre-set interactions with Google Calendar on the [Hub](https://hub.windmill.dev/integrations/gcal).