This skill provides comprehensive guidance for adding new native trigger services to Windmill. Native triggers allow external services (like Nextcloud, Google Drive, etc.) to trigger Windmill scripts/flows via webhooks or push notifications.
Architecture Overview
The native trigger system consists of:
- Database Layer - PostgreSQL tables and enum types
- Backend Rust Implementation - Core trait, handlers, and service modules in the
windmill-native-triggerscrate - Frontend Svelte Components - Configuration forms and UI components
Key Files
| Component | Path |
|---|---|
Core module with External trait |
backend/windmill-native-triggers/src/lib.rs |
| Generic CRUD handlers | backend/windmill-native-triggers/src/handler.rs |
| Background sync logic | backend/windmill-native-triggers/src/sync.rs |
| OAuth/workspace integration | backend/windmill-native-triggers/src/workspace_integrations.rs |
| Re-export shim (windmill-api) | backend/windmill-api/src/native_triggers/mod.rs |
| TriggerKind enum | backend/windmill-common/src/triggers.rs |
| JobTriggerKind enum | backend/windmill-common/src/jobs.rs |
| Frontend service registry | frontend/src/lib/components/triggers/native/utils.ts |
| Frontend trigger utilities | frontend/src/lib/components/triggers/utils.ts |
| Trigger badges (icons + counts) | frontend/src/lib/components/graph/renderers/triggers/TriggersBadge.svelte |
| Workspace integrations UI | frontend/src/lib/components/workspaceSettings/WorkspaceIntegrations.svelte |
| OAuth config form component | frontend/src/lib/components/workspaceSettings/OAuthClientConfig.svelte |
| OpenAPI spec | backend/windmill-api/openapi.yaml |
| Reference: Nextcloud module | backend/windmill-native-triggers/src/nextcloud/ |
| Reference: Google module | backend/windmill-native-triggers/src/google/ |
Crate Structure
The native trigger code lives in the windmill-native-triggers crate (backend/windmill-native-triggers/). The windmill-api crate re-exports everything via a shim:
// backend/windmill-api/src/native_triggers/mod.rs
pub use windmill_native_triggers::*;
All new service modules go in backend/windmill-native-triggers/src/.
Core Concepts
The External Trait
Every native trigger service implements the External trait defined in lib.rs:
#[async_trait]
pub trait External: Send + Sync + 'static {
// Associated types:
type ServiceConfig: Debug + DeserializeOwned + Serialize + Send + Sync;
type TriggerData: Debug + Serialize + Send + Sync;
type OAuthData: DeserializeOwned + Serialize + Clone + Send + Sync;
type CreateResponse: DeserializeOwned + Send + Sync;
// Constants:
const SUPPORT_WEBHOOK: bool;
const SERVICE_NAME: ServiceName;
const DISPLAY_NAME: &'static str;
const TOKEN_ENDPOINT: &'static str;
const REFRESH_ENDPOINT: &'static str;
const AUTH_ENDPOINT: &'static str;
// Required methods:
async fn create(&self, w_id, oauth_data, webhook_token, data, db, tx) -> Result<Self::CreateResponse>;
async fn update(&self, w_id, oauth_data, external_id, webhook_token, data, db, tx) -> Result<serde_json::Value>;
async fn get(&self, w_id, oauth_data, external_id, db, tx) -> Result<Self::TriggerData>;
async fn delete(&self, w_id, oauth_data, external_id, db, tx) -> Result<()>;
async fn exists(&self, w_id, oauth_data, external_id, db, tx) -> Result<bool>;
async fn maintain_triggers(&self, db, workspace_id, triggers, oauth_data, synced, errors);
fn external_id_and_metadata_from_response(&self, resp) -> (String, Option<serde_json::Value>);
// Methods with defaults:
async fn prepare_webhook(&self, db, w_id, headers, body, script_path, is_flow) -> Result<PushArgsOwned>;
fn service_config_from_create_response(&self, data, resp) -> Option<serde_json::Value>;
fn additional_routes(&self) -> axum::Router;
async fn http_client_request<T, B>(&self, url, method, workspace_id, tx, db, headers, body) -> Result<T>;
}
Key design points:
update()returnsserde_json::Value- the resolved service_config to store. Each service is responsible for building the final config.maintain_triggers()- periodic background maintenance. Each service implements its own strategy (Nextcloud: reconcile with external state; Google: renew expiring channels).- No
list_all()in the trait - services that need it (Nextcloud) implement it privately; services that don't (Google) use different maintenance strategies. - No
get_external_id_from_trigger_data()orextract_service_config_from_trigger_data()- removed in favor of themaintain_triggerspattern.
Create Lifecycle: Two Paths
The create_native_trigger handler in handler.rs supports two creation flows, controlled by service_config_from_create_response():
Path A: Short (Google pattern) - service_config_from_create_response() returns Some(config):
create()registers on external serviceexternal_id_and_metadata_from_response()extracts the IDservice_config_from_create_response()builds the config directly from input data + response metadata- Stores trigger in DB -- done, no extra round-trip
Use this when the external_id is known before the create call (e.g., Google generates the channel_id as a UUID upfront and includes it in the webhook URL).
Path B: Long (Nextcloud pattern) - service_config_from_create_response() returns None (default):
create()registers on external service (webhook URL has no external_id yet)external_id_and_metadata_from_response()extracts the IDupdate()is called to fix the webhook URL with the now-known external_idupdate()returns the resolved service_config- Stores trigger in DB
Use this when the external_id is assigned by the remote service and the webhook URL needs to be corrected after creation.
OAuth Token Storage (Three-Table Pattern)
OAuth tokens are stored across three tables, NOT in workspace_integrations.oauth_data directly:
| Table | What's Stored |
|---|---|
workspace_integrations |
oauth_data JSON with base_url, client_id, client_secret, instance_shared flag; resource_path pointing to the variable |
variable |
Encrypted access_token (at the path stored in resource_path), linked to account via account column |
account |
refresh_token, keyed by workspace_id + client (service name) + is_workspace_integration = true |
The decrypt_oauth_data() function in lib.rs assembles these into a unified struct:
pub struct OAuthConfig {
pub base_url: String,
pub access_token: String, // decrypted from variable
pub refresh_token: Option<String>, // from account table
pub client_id: String, // from oauth_data or instance settings
pub client_secret: String, // from oauth_data or instance settings
}
Instance-level sharing: when oauth_data.instance_shared == true, client_id and client_secret are read from global settings instead of workspace_integrations.
URL Resolution
The resolve_endpoint() helper handles both absolute and relative OAuth URLs:
pub fn resolve_endpoint(base_url: &str, endpoint: &str) -> String {
if endpoint.starts_with("http://") || endpoint.starts_with("https://") {
endpoint.to_string() // Google: absolute URLs
} else {
format!("{}{}", base_url, endpoint) // Nextcloud: relative paths
}
}
ServiceName Methods
ServiceName is the central registry enum. Each variant must implement these match arms:
| Method | Purpose |
|---|---|
as_str() |
Lowercase identifier (e.g., "google") |
as_trigger_kind() |
Maps to TriggerKind enum |
as_job_trigger_kind() |
Maps to JobTriggerKind enum |
token_endpoint() |
OAuth token endpoint (relative or absolute) |
auth_endpoint() |
OAuth authorization endpoint |
oauth_scopes() |
Space-separated OAuth scopes |
resource_type() |
Resource type for token storage (e.g., "gworkspace") |
extra_auth_params() |
Extra OAuth params (e.g., Google needs access_type=offline, prompt=consent) |
integration_service() |
Maps to the workspace integration service (usually *self) |
TryFrom<String> |
Parse from string |
Display |
Delegates to as_str() |
Step-by-Step Implementation Guide
Step 1: Database Migration
Create a new migration file: backend/migrations/YYYYMMDDHHMMSS_newservice_trigger.up.sql
-- Add the service to the native_trigger_service enum
ALTER TYPE native_trigger_service ADD VALUE IF NOT EXISTS 'newservice';
-- Add to TRIGGER_KIND enum (used for trigger tracking)
ALTER TYPE TRIGGER_KIND ADD VALUE IF NOT EXISTS 'newservice';
-- Add to job_trigger_kind enum (used for job tracking)
ALTER TYPE job_trigger_kind ADD VALUE IF NOT EXISTS 'newservice';
Also create the corresponding down migration.
Step 2: Update windmill-common Enums
backend/windmill-common/src/triggers.rs
Add variant to TriggerKind enum, and update to_key() and fmt() implementations.
backend/windmill-common/src/jobs.rs
Add variant to JobTriggerKind enum and update the Display implementation.
Step 3: Backend Service Module
Create a new directory: backend/windmill-native-triggers/src/newservice/
mod.rs - Type Definitions
use serde::{Deserialize, Serialize};
pub mod external;
// pub mod routes; // Only if you need additional service-specific routes
/// OAuth data deserialized from the three-table pattern.
/// The actual structure is built by decrypt_oauth_data() from variable + account + workspace_integrations.
#[derive(Debug, Clone, Deserialize, Serialize)]
pub struct NewServiceOAuthData {
pub base_url: String, // from workspace_integrations.oauth_data
pub access_token: String, // decrypted from variable table
pub refresh_token: Option<String>, // from account table
// Note: client_id and client_secret are in OAuthConfig, not here
// unless the service needs them at runtime for API calls
}
/// Configuration provided by user when creating/updating a trigger.
/// Stored as JSON in native_trigger.service_config.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct NewServiceConfig {
// Service-specific configuration fields
pub folder_path: String,
pub file_filter: Option<String>,
}
/// Data retrieved from the external service about a trigger.
/// Returned by the get() method and shown in the UI.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct NewServiceTriggerData {
pub folder_path: String,
pub file_filter: Option<String>,
// Fields that shouldn't affect service_config comparison should use #[serde(skip_serializing)]
}
/// Response from external service when creating a trigger/webhook.
#[derive(Debug, Deserialize)]
pub struct CreateTriggerResponse {
pub id: String,
}
/// Handler struct (stateless, used for routing)
#[derive(Copy, Clone)]
pub struct NewService;
external.rs - External Trait Implementation
use async_trait::async_trait;
use reqwest::Method;
use sqlx::PgConnection;
use std::collections::HashMap;
use windmill_common::{
error::{Error, Result},
BASE_URL, DB,
};
use crate::{
generate_webhook_service_url, External, NativeTrigger, NativeTriggerData, ServiceName,
sync::{SyncError, TriggerSyncInfo},
};
use super::{NewService, NewServiceConfig, NewServiceOAuthData, NewServiceTriggerData, CreateTriggerResponse};
#[async_trait]
impl External for NewService {
type ServiceConfig = NewServiceConfig;
type TriggerData = NewServiceTriggerData;
type OAuthData = NewServiceOAuthData;
type CreateResponse = CreateTriggerResponse;
const SERVICE_NAME: ServiceName = ServiceName::NewService;
const DISPLAY_NAME: &'static str = "New Service";
const SUPPORT_WEBHOOK: bool = true;
const TOKEN_ENDPOINT: &'static str = "/oauth/token";
const REFRESH_ENDPOINT: &'static str = "/oauth/token";
const AUTH_ENDPOINT: &'static str = "/oauth/authorize";
async fn create(
&self,
w_id: &str,
oauth_data: &Self::OAuthData,
webhook_token: &str,
data: &NativeTriggerData<Self::ServiceConfig>,
db: &DB,
tx: &mut PgConnection,
) -> Result<Self::CreateResponse> {
let base_url = &*BASE_URL.read().await;
// external_id is None during create (we get it from the response)
let webhook_url = generate_webhook_service_url(
base_url, w_id, &data.script_path, data.is_flow,
None, Self::SERVICE_NAME, webhook_token,
);
let url = format!("{}/api/webhooks/create", oauth_data.base_url);
let payload = serde_json::json!({
"callback_url": webhook_url,
"folder_path": data.service_config.folder_path,
});
let response: CreateTriggerResponse = self
.http_client_request(&url, Method::POST, w_id, tx, db, None, Some(&payload))
.await?;
Ok(response)
}
/// Update returns the resolved service_config as JSON.
/// For services using the update+get pattern, call self.get() and serialize.
async fn update(
&self,
w_id: &str,
oauth_data: &Self::OAuthData,
external_id: &str,
webhook_token: &str,
data: &NativeTriggerData<Self::ServiceConfig>,
db: &DB,
tx: &mut PgConnection,
) -> Result<serde_json::Value> {
let base_url = &*BASE_URL.read().await;
let webhook_url = generate_webhook_service_url(
base_url, w_id, &data.script_path, data.is_flow,
Some(external_id), Self::SERVICE_NAME, webhook_token,
);
let url = format!("{}/api/webhooks/{}", oauth_data.base_url, external_id);
let payload = serde_json::json!({
"callback_url": webhook_url,
"folder_path": data.service_config.folder_path,
});
let _: serde_json::Value = self
.http_client_request(&url, Method::PUT, w_id, tx, db, None, Some(&payload))
.await?;
// Fetch back the updated state to get the resolved config
let trigger_data = self.get(w_id, oauth_data, external_id, db, tx).await?;
serde_json::to_value(&trigger_data)
.map_err(|e| Error::InternalErr(format!("Failed to serialize trigger data: {}", e)))
}
async fn get(
&self,
w_id: &str,
oauth_data: &Self::OAuthData,
external_id: &str,
db: &DB,
tx: &mut PgConnection,
) -> Result<Self::TriggerData> {
let url = format!("{}/api/webhooks/{}", oauth_data.base_url, external_id);
self.http_client_request::<_, ()>(&url, Method::GET, w_id, tx, db, None, None).await
}
async fn delete(
&self,
w_id: &str,
oauth_data: &Self::OAuthData,
external_id: &str,
db: &DB,
tx: &mut PgConnection,
) -> Result<()> {
let url = format!("{}/api/webhooks/{}", oauth_data.base_url, external_id);
let _: serde_json::Value = self
.http_client_request::<_, ()>(&url, Method::DELETE, w_id, tx, db, None, None)
.await
.or_else(|e| match &e {
Error::InternalErr(msg) if msg.contains("404") => Ok(serde_json::Value::Null),
_ => Err(e),
})?;
Ok(())
}
async fn exists(
&self,
w_id: &str,
oauth_data: &Self::OAuthData,
external_id: &str,
db: &DB,
tx: &mut PgConnection,
) -> Result<bool> {
match self.get(w_id, oauth_data, external_id, db, tx).await {
Ok(_) => Ok(true),
Err(Error::NotFound(_)) => Ok(false),
Err(e) => Err(e),
}
}
/// Background maintenance. Choose the right pattern for your service:
/// - For services with queryable external state: use reconcile_with_external_state()
/// - For channel-based services with expiration: implement renewal logic
async fn maintain_triggers(
&self,
db: &DB,
workspace_id: &str,
triggers: &[NativeTrigger],
oauth_data: &Self::OAuthData,
synced: &mut Vec<TriggerSyncInfo>,
errors: &mut Vec<SyncError>,
) {
// Option A: Reconcile with external state (Nextcloud pattern)
// Fetch all triggers from external service and compare with DB
let external_triggers = match self.list_all(workspace_id, oauth_data, db).await {
Ok(triggers) => triggers,
Err(e) => {
errors.push(SyncError {
resource_path: format!("workspace:{}", workspace_id),
error_message: format!("Failed to list triggers: {}", e),
error_type: "api_error".to_string(),
});
return;
}
};
// Convert to (external_id, config_json) pairs
let external_pairs: Vec<(String, serde_json::Value)> = external_triggers
.into_iter()
.map(|t| (t.id.clone(), serde_json::to_value(&t).unwrap_or_default()))
.collect();
crate::sync::reconcile_with_external_state(
db, workspace_id, Self::SERVICE_NAME, triggers, &external_pairs, synced, errors,
).await;
}
fn external_id_and_metadata_from_response(
&self,
resp: &Self::CreateResponse,
) -> (String, Option<serde_json::Value>) {
(resp.id.clone(), None)
}
// service_config_from_create_response: NOT overridden (returns None).
// This means the handler uses the update+get pattern after create.
// Override and return Some(...) to skip the update+get cycle (Google pattern).
}
impl NewService {
/// Private helper to list all triggers from the external service.
async fn list_all(
&self,
w_id: &str,
oauth_data: &<Self as External>::OAuthData,
db: &DB,
) -> Result<Vec<<Self as External>::TriggerData>> {
// Implementation depends on the external service's API
todo!()
}
}
Step 4: Update lib.rs Registry
In backend/windmill-native-triggers/src/lib.rs:
// Service modules - add new services here:
#[cfg(feature = "native_trigger")]
pub mod newservice; // <-- Add this
// ServiceName enum - add variant:
pub enum ServiceName {
Nextcloud,
Google,
NewService, // <-- Add this
}
// Then add match arms in ALL ServiceName methods:
// as_str(), as_trigger_kind(), as_job_trigger_kind(), token_endpoint(),
// auth_endpoint(), oauth_scopes(), resource_type(), extra_auth_params(),
// integration_service(), TryFrom<String>, Display
Step 5: Update handler.rs Routes
In backend/windmill-native-triggers/src/handler.rs:
pub fn generate_native_trigger_routers() -> Router {
// ...
#[cfg(feature = "native_trigger")]
{
use crate::newservice::NewService;
return router
.nest("/nextcloud", service_routes(NextCloud))
.nest("/google", service_routes(Google))
.nest("/newservice", service_routes(NewService)); // <-- Add this
}
// ...
}
Step 6: Update sync.rs
In backend/windmill-native-triggers/src/sync.rs:
pub async fn sync_all_triggers(db: &DB) -> Result<BackgroundSyncResult> {
// ...
#[cfg(feature = "native_trigger")]
{
use crate::newservice::NewService;
// ... existing service syncs ...
// New service sync
let (service_name, result) = sync_service_triggers(db, NewService).await;
total_synced += result.synced_triggers.len();
total_errors += result.errors.len();
service_results.insert(service_name, result);
}
// ...
}
Step 7: Frontend Service Registry
In frontend/src/lib/components/triggers/native/utils.ts:
Add to NATIVE_TRIGGER_SERVICES, getTriggerIconName(), and getServiceIcon().
Step 8: Frontend Trigger Form Component
Create: frontend/src/lib/components/triggers/native/services/newservice/NewServiceTriggerForm.svelte
Step 9: Frontend Icon Component
Create: frontend/src/lib/components/icons/NewServiceIcon.svelte
Step 10: Update NativeTriggerEditor
Check frontend/src/lib/components/triggers/native/NativeTriggerEditor.svelte to ensure it dynamically loads form components based on service name.
Step 11: Workspace Integration UI
Add your service to the supportedServices map in frontend/src/lib/components/workspaceSettings/WorkspaceIntegrations.svelte:
const supportedServices: Record<string, ServiceConfig> = {
// ... existing services ...
newservice: {
name: 'newservice',
displayName: 'New Service',
description: 'Connect to New Service for triggers',
icon: NewServiceIcon,
docsUrl: 'https://www.windmill.dev/docs/integrations/newservice',
requiresBaseUrl: false, // false for cloud services, true for self-hosted
setupInstructions: [
'Step 1: Create an OAuth app on the service',
'Step 2: Configure the redirect URI shown below',
'Step 3: Enter the client credentials below'
]
}
}
Step 12: Update frontend/src/lib/components/triggers/utils.ts
Update ALL of these maps/functions:
triggerIconMap- import and add icontriggerDisplayNamesMap- add display nametriggerTypeOrderinsortTriggers()- add typegetLightConfig()- add case for your servicegetTriggerLabel()- add case for your servicejobTriggerKinds- add to arraycountPropertyMap- add count propertytriggerSaveFunctions- add save function
Step 13: Update TriggersBadge Component
In frontend/src/lib/components/graph/renderers/triggers/TriggersBadge.svelte:
- Import the icon
- Add to
baseConfigwithcountKey(the dynamicavailableNativeServicesloop does NOT setcountKey) - Add to the
allTypesarray
Step 14: Update TriggersWrapper.svelte
In frontend/src/lib/components/triggers/TriggersWrapper.svelte:
Add a {:else if selectedTrigger.type === 'yourservice'} case that renders <NativeTriggersPanel service="yourservice" ...> with the same props pattern as the existing native trigger cases (e.g., nextcloud).
Step 15: Update AddTriggersButton.svelte
In frontend/src/lib/components/triggers/AddTriggersButton.svelte:
- Add
yourserviceAvailablestate variable - Add
setYourserviceState()async function usingisServiceAvailable('yourservice', $workspaceStore!) - Call it at module level
- Add a dropdown entry to
addTriggerItemswithhidden: !yourserviceAvailable
Step 16: Update TriggersEditor.svelte Delete Handling
In frontend/src/lib/components/triggers/TriggersEditor.svelte:
Add your service to the nativeTriggerServices map in deleteDeployedTrigger(). Native triggers use NativeTriggerService.deleteNativeTrigger({ workspace, serviceName, externalId }) instead of the standard path-based delete.
Step 17: Update getUsedTriggers for Sidebar Visibility
The sidebar (frontend/src/lib/components/sidebar/SidebarContent.svelte) shows native-trigger links only if $usedTriggerKinds includes the service — without this, your trigger page will never appear in the nav bar even when triggers exist.
- Backend — add
{service}_used: boolto theUsedTriggersstruct and SELECT inbackend/windmill-api-workspaces/src/workspaces.rs::get_used_triggers():EXISTS(SELECT 1 FROM native_trigger WHERE workspace_id = $1 AND service_name = '{service}'::native_trigger_service) AS "{service}_used!" - OpenAPI — add
{service}_used: booleanto the response schema forGET /w/{workspace}/workspaces/used_triggers(under bothpropertiesandrequired). - Layout — in
frontend/src/routes/(root)/(logged)/+layout.svelte::loadUsedTriggerKinds(), destructure{service}_usedand push'{service}'tousedKinds.
Step 18: Update OpenAPI Spec and Regenerate Types
Add to JobTriggerKind enum in backend/windmill-api/openapi.yaml, then:
cd frontend && npm run generate-backend-client
Special Patterns
Unified Service with trigger_type (Google Pattern)
When a single service handles multiple trigger types (e.g., Google Drive + Calendar share OAuth and API patterns), use a single ServiceName variant with a discriminator field:
pub enum GoogleTriggerType { Drive, Calendar }
pub struct GoogleServiceConfig {
pub trigger_type: GoogleTriggerType,
// Drive-specific fields (only used when trigger_type = Drive)
pub resource_id: Option<String>,
pub resource_name: Option<String>,
// Calendar-specific fields (only used when trigger_type = Calendar)
pub calendar_id: Option<String>,
pub calendar_name: Option<String>,
// Metadata set after creation
pub google_resource_id: Option<String>,
pub expiration: Option<String>,
}
Branch in trait methods based on trigger_type. Frontend uses a ToggleButtonGroup to switch between types. This keeps the codebase simpler (one service, one OAuth flow, one set of routes).
See backend/windmill-native-triggers/src/google/ for the reference implementation.
Skipping update+get After Create (Google Pattern)
Override service_config_from_create_response() to return Some(config) when the external_id is known before the create call:
fn service_config_from_create_response(
&self,
data: &NativeTriggerData<Self::ServiceConfig>,
resp: &Self::CreateResponse,
) -> Option<serde_json::Value> {
// Clone input config, add metadata from response
let mut config = data.service_config.clone();
config.google_resource_id = Some(resp.resource_id.clone());
config.expiration = Some(resp.expiration.clone());
Some(serde_json::to_value(&config).unwrap())
}
Services with Absolute OAuth Endpoints (Google)
Unlike self-hosted services where OAuth endpoints are relative paths appended to base_url, services like Google have absolute URLs:
// Nextcloud: relative paths
ServiceName::Nextcloud => "/apps/oauth2/api/v1/token",
// Google: absolute URLs
ServiceName::Google => "https://oauth2.googleapis.com/token",
The resolve_endpoint() function handles both. For services with absolute endpoints:
base_urlcan be emptyrequiresBaseUrl: falsein the frontend workspace integration config- Add
extra_auth_params()if needed (Google requiresaccess_type=offlineandprompt=consent)
Channel-Based Push Notifications with Renewal (Google Pattern)
For services using expiring watch channels instead of persistent webhooks:
- Store expiration in
service_config(as part ofServiceConfig) - In
maintain_triggers(), implement renewal logic instead of usingreconcile_with_external_state():async fn maintain_triggers(&self, db, workspace_id, triggers, oauth_data, synced, errors) { for trigger in triggers { if should_renew_channel(trigger) { self.renew_channel(db, trigger, oauth_data).await; } } } - Renewal: best-effort stop old channel, create new one with same external_id, update service_config with new expiration
- Google example: Drive channels expire in 24h (renew when <1h left), Calendar channels expire in 7 days (renew when <1 day left)
reconcile_with_external_state (Nextcloud Pattern)
The reusable function in sync.rs compares external triggers with DB state:
- Triggers missing externally: sets error "Trigger no longer exists on external service"
- Triggers present externally: clears errors, updates service_config if it differs
Usage in maintain_triggers():
let external_pairs: Vec<(String, serde_json::Value)> = /* fetch from external */;
crate::sync::reconcile_with_external_state(
db, workspace_id, Self::SERVICE_NAME, triggers, &external_pairs, synced, errors,
).await;
Webhook Payload Processing
Override prepare_webhook() to parse service-specific payloads into script/flow args:
async fn prepare_webhook(&self, db, w_id, headers, body, script_path, is_flow) -> Result<PushArgsOwned> {
let mut args = HashMap::new();
args.insert("event_type".to_string(), Box::new(headers.get("x-event-type").cloned()) as _);
args.insert("payload".to_string(), Box::new(serde_json::from_str::<serde_json::Value>(&body)?) as _);
Ok(PushArgsOwned { extra: None, args })
}
Then register in prepare_native_trigger_args() in lib.rs:
pub async fn prepare_native_trigger_args(service_name, db, w_id, headers, body) -> Result<Option<PushArgsOwned>> {
match service_name {
ServiceName::Google => { /* ... */ Ok(Some(args)) }
ServiceName::NewService => { /* ... */ Ok(Some(args)) }
ServiceName::Nextcloud => Ok(None), // Uses default body parsing
}
}
Instance-Level OAuth Credentials
When workspace_integrations.oauth_data.instance_shared == true, decrypt_oauth_data() reads client_id and client_secret from instance-level global settings instead of workspace-level. This allows admins to share OAuth app credentials across workspaces.
The frontend handles this via the generate_instance_connect_url endpoint in workspace_integrations.rs.
Testing Checklist
- Database migration runs successfully
-
cargo check -p windmill-native-triggers --features native_triggerpasses -
npx svelte-check --threshold errorpasses (in frontend/) - Service appears in workspace integrations list
- OAuth flow completes successfully
- Can create a new trigger
- Can view trigger details
- Can update trigger configuration
- Can delete trigger
- Webhook receives and processes payloads
- Background sync works correctly (reconciliation or channel renewal)
- Error handling works (expired tokens, service unavailable)
Reference Implementations
Nextcloud (Self-Hosted, Update+Get Pattern)
| File | Purpose |
|---|---|
nextcloud/mod.rs |
Types: NextCloudOAuthData, NextcloudServiceConfig, NextCloudTriggerData |
nextcloud/external.rs |
External trait: uses update+get pattern, reconcile_with_external_state for sync |
nextcloud/routes.rs |
Additional route: GET /events |
Key patterns: relative OAuth endpoints, base_url required, list_all + reconcile for sync, update returns JSON from get().
Google (Cloud, Unified Service, Short Create)
| File | Purpose |
|---|---|
google/mod.rs |
Types: GoogleServiceConfig with trigger_type discriminator, GoogleTriggerType enum |
google/external.rs |
External trait: overrides service_config_from_create_response, channel renewal for sync |
google/routes.rs |
Additional routes: GET /calendars, GET /drive/files, GET /drive/shared_drives |
Key patterns: absolute OAuth endpoints, empty base_url, trigger_type for Drive/Calendar, expiring watch channels with renewal, service_config_from_create_response skips update+get, get() reconstructs data from stored service_config (no external "get channel" API).