Skip to content

Commit 8cedd2a

Browse files
github-actions[bot]claude
github-actions[bot]
and
claude
committed
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>
1 parent 58abaab commit 8cedd2a

File tree

4 files changed

+191
-0
lines changed

4 files changed

+191
-0
lines changed

‎docs/core_concepts/52_native_triggers/index.mdx‎

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
---
2+
description: How do I trigger scripts and flows from Nextcloud or Google Drive/Calendar events in Windmill?
3+
---
4+
5+
import DocCard from '@site/src/components/DocCard';
6+
7+
# Native triggers
8+
9+
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 or watch channels, so your runnables execute as soon as events occur.
10+
11+
Native triggers is a [self-hosted Enterprise](/pricing) feature.
12+
13+
Currently supported services:
14+
15+
- [Nextcloud](#nextcloud-triggers) - file and folder change events
16+
- [Google Drive](#google-drive-triggers) - file and folder change events
17+
- [Google Calendar](#google-calendar-triggers) - calendar event changes
18+
19+
---
20+
21+
## How it works
22+
23+
Native triggers use OAuth 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.
24+
25+
The general setup follows two steps:
26+
27+
1. **Connect the service** via workspace settings (OAuth authentication)
28+
2. **Create a trigger** on a script or flow, selecting the service and configuring which events to watch
29+
30+
---
31+
32+
## Setup
33+
34+
### Workspace integration
35+
36+
Before creating native triggers, you need to connect the external service in your workspace settings.
37+
38+
1. Go to **Workspace settings** > **Integrations**
39+
2. Select the service you want to connect (Nextcloud or Google)
40+
3. Provide the OAuth credentials (client ID and client secret)
41+
4. Complete the OAuth authorization flow
42+
43+
<!-- TODO: add screenshot of workspace integrations page -->
44+
45+
For Google triggers, instance admins can optionally share OAuth credentials across workspaces, so individual workspace admins don't need to create their own Google OAuth app.
46+
47+
For Nextcloud, you also need to provide the base URL of your Nextcloud instance.
48+
49+
### Create a trigger
50+
51+
Once the workspace integration is configured:
52+
53+
1. Open the script or flow you want to trigger
54+
2. Go to the **Triggers** tab
55+
3. Select **Native trigger** and choose the service
56+
4. Configure the service-specific options (see sections below)
57+
5. Save the trigger
58+
59+
<!-- TODO: add screenshot of trigger creation -->
60+
61+
---
62+
63+
## Nextcloud triggers
64+
65+
Nextcloud native triggers watch for file and folder changes on a [Nextcloud](https://nextcloud.com/) instance and trigger a script or flow when events occur.
66+
67+
### Prerequisites
68+
69+
- A Nextcloud instance with OAuth2 configured
70+
- The Nextcloud OAuth2 app enabled and a client registered
71+
72+
### Configuration
73+
74+
When creating a Nextcloud trigger, configure:
75+
76+
- **Events** - select which event types to watch (e.g. file created, file updated, file deleted)
77+
78+
<!-- TODO: add screenshot of Nextcloud trigger configuration -->
79+
80+
---
81+
82+
## Google Drive triggers
83+
84+
Google Drive native triggers watch for changes to files or folders in [Google Drive](https://drive.google.com/) and trigger a script or flow when modifications occur.
85+
86+
### Prerequisites
87+
88+
- A Google Cloud project with the Google Drive API enabled
89+
- OAuth 2.0 credentials (client ID and client secret) configured with the appropriate scopes
90+
91+
### Configuration
92+
93+
When creating a Google Drive trigger, configure:
94+
95+
- **File or folder** - select a file or folder from your Google Drive to watch for changes. You can browse My Drive, Shared with me, and Shared drives.
96+
97+
<!-- TODO: add screenshot of Google Drive trigger configuration with file picker -->
98+
99+
Google Drive triggers use push notifications via [watch channels](https://developers.google.com/drive/api/guides/push). Channels expire after 24 hours and Windmill automatically renews them before expiration.
100+
101+
---
102+
103+
## Google Calendar triggers
104+
105+
Google Calendar native triggers watch for changes to events in a [Google Calendar](https://calendar.google.com/) and trigger a script or flow when calendar events are created, updated, or deleted.
106+
107+
### Prerequisites
108+
109+
- A Google Cloud project with the Google Calendar API enabled
110+
- OAuth 2.0 credentials (client ID and client secret) configured with the appropriate scopes
111+
112+
### Configuration
113+
114+
When creating a Google Calendar trigger, configure:
115+
116+
- **Calendar** - select a calendar from your Google account to watch for event changes
117+
118+
<!-- TODO: add screenshot of Google Calendar trigger configuration with calendar picker -->
119+
120+
Google Calendar triggers use push notifications via [watch channels](https://developers.google.com/calendar/api/guides/push). Channels expire after 7 days and Windmill automatically renews them before expiration.
121+
122+
---
123+
124+
## Implementation examples
125+
126+
### Basic script
127+
128+
The trigger passes event data as arguments to your script. The payload format depends on the service.
129+
130+
```typescript
131+
export async function main(payload: object) {
132+
console.log("Received event:", JSON.stringify(payload));
133+
return { processed: true };
134+
}
135+
```
136+
137+
### Using a preprocessor
138+
139+
If you configure a [preprocessor](../43_preprocessors/index.mdx), you can transform the event data before it reaches the main function.
140+
141+
```typescript
142+
export async function preprocessor(
143+
event: {
144+
kind: 'google' | 'nextcloud',
145+
payload: object,
146+
}
147+
) {
148+
if (event.kind === 'google') {
149+
return {
150+
payload: event.payload,
151+
};
152+
}
153+
154+
throw new Error(`Expected google or nextcloud trigger kind, got: ${event.kind}`);
155+
}
156+
```
157+
158+
Then your `main` function receives the processed data:
159+
160+
```typescript
161+
export async function main(payload: object) {
162+
console.log("Processed event:", JSON.stringify(payload));
163+
}
164+
```
165+
166+
## Error handling
167+
168+
Native triggers support local error handlers that override workspace error handlers for specific triggers. See the [error handling documentation](../10_error_handling/index.mdx#trigger-error-handlers) for configuration details and examples.

‎docs/core_concepts/index.mdx‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,11 @@ On top of its editors to build endpoints, flows, [low-code apps](../apps/0_app_e
7171
description="Trigger scripts and flows from Google Cloud Pub/Sub messages."
7272
href="/docs/core_concepts/gcp_triggers"
7373
/>
74+
<DocCard
75+
title="Native triggers"
76+
description="Trigger scripts and flows from Nextcloud, Google Drive, and Google Calendar events."
77+
href="/docs/core_concepts/native_triggers"
78+
/>
7479
</div>
7580

7681
## Windmill features

‎docs/getting_started/8_triggers/index.mdx‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@ Triggers from external events:
3131
- [SQS triggers](#sqs-triggers)
3232
- [MQTT triggers](#mqtt-triggers)
3333
- [GCP triggers](#gcp-triggers)
34+
- [Native triggers](#native-triggers) (Nextcloud, Google Drive, Google Calendar)
3435
- [Scheduled polls](#scheduled-polls-scheduling--trigger-scripts)
3536

3637
:::info Scripts and Flows in Windmill
@@ -364,6 +365,18 @@ Windmill can connect to Google Cloud Pub/Sub, subscribe to specific topics, and
364365
</div>
365366

366367

368+
### Native triggers
369+
370+
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.
371+
372+
<div className="grid grid-cols-2 gap-6 mb-4">
373+
<DocCard
374+
title="Native triggers"
375+
description="Trigger scripts and flows from Nextcloud, Google Drive, and Google Calendar events."
376+
href="/docs/core_concepts/native_triggers"
377+
/>
378+
</div>
379+
367380
### Scheduled polls (Scheduling + Trigger scripts)
368381

369382
A particular use case for schedules are [Trigger scripts](../../flows/10_flow_trigger.mdx).

‎sidebars.js‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -182,6 +182,11 @@ const sidebars = {
182182
type: 'doc',
183183
id: 'core_concepts/gcp_triggers/index',
184184
label: 'GCP'
185+
},
186+
{
187+
type: 'doc',
188+
id: 'core_concepts/native_triggers/index',
189+
label: 'Native triggers'
185190
}
186191
]
187192
},

0 commit comments

Comments
 (0)