Native Trigger

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() returns serde_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() or extract_service_config_from_trigger_data() - removed in favor of the maintain_triggers pattern.

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):

1. create() registers on external service
2. external_id_and_metadata_from_response() extracts the ID
3. service_config_from_create_response() builds the config directly from input data + response metadata
4. 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):

1. create() registers on external service (webhook URL has no external_id yet)
2. external_id_and_metadata_from_response() extracts the ID
3. update() is called to fix the webhook URL with the now-known external_id
4. update() returns the resolved service_config
5. 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:

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:

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:

1. triggerIconMap - import and add icon
2. triggerDisplayNamesMap - add display name
3. triggerTypeOrder in sortTriggers() - add type
4. getLightConfig() - add case for your service
5. getTriggerLabel() - add case for your service
6. jobTriggerKinds - add to array
7. countPropertyMap - add count property
8. triggerSaveFunctions - add save function

Step 13: Update TriggersBadge Component

In frontend/src/lib/components/graph/renderers/triggers/TriggersBadge.svelte:

1. Import the icon
2. Add to baseConfig with countKey (the dynamic availableNativeServices loop does NOT set countKey)
3. Add to the allTypes array

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:

1. Add yourserviceAvailable state variable
2. Add setYourserviceState() async function using isServiceAvailable('yourservice', $workspaceStore!)
3. Call it at module level
4. Add a dropdown entry to addTriggerItems with hidden: !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.

1. Backend — add {service}_used: bool to the UsedTriggers struct and SELECT in backend/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!"
   

2. OpenAPI — add {service}_used: boolean to the response schema for GET /w/{workspace}/workspaces/used_triggers (under both properties and required).
3. Layout — in frontend/src/routes/(root)/(logged)/+layout.svelte::loadUsedTriggerKinds(), destructure {service}_used and push '{service}' to usedKinds.

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_url can be empty
• requiresBaseUrl: false in the frontend workspace integration config
• Add extra_auth_params() if needed (Google requires access_type=offline and prompt=consent)

Channel-Based Push Notifications with Renewal (Google Pattern)

For services using expiring watch channels instead of persistent webhooks:

1. Store expiration in service_config (as part of ServiceConfig)
2. In maintain_triggers(), implement renewal logic instead of using reconcile_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;
           }
       }
   }
   

3. Renewal: best-effort stop old channel, create new one with same external_id, update service_config with new expiration
4. 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 */;