Skip to content

Integration with Zapier

Jump to bottom
rolandm99 edited this page Sep 23, 2025 · 1 revision

Integration with Zapier

The Zapier integration enables seamless automation between Gauzy and thousands of other apps through Zapier's powerful automation platform. This integration allows you to create custom workflows, automate tasks, and synchronize data across multiple platforms.

Overview

The Gauzy Zapier integration provides:

  • OAuth2 Authentication: Secure authentication using the standard OAuth2 flow
  • REST Hook Triggers: Real-time webhook notifications for instant automation
  • Timer Management Actions: Start and stop timers remotely through Zapier workflows
  • Dynamic Dropdowns: Context-aware field options for tenants, organizations, projects, tasks, etc.
  • Multi-tenant Support: Organization and tenant-level integration settings
  • Webhook Management: Secure webhook subscription and lifecycle management

Features

Triggers (When this happens...)

  • Timer Status Changed: Triggers when a timer status changes in Gauzy (start, stop, pause, resume)

Actions (Do this...)

  • Start Timer: Start a new timer with specified parameters
  • Stop Timer: Stop an existing running timer
  • Timer Status: Get current timer status information

Dynamic Dropdowns

  • Tenant List: Select from available tenants
  • Organization List: Select from available organizations
  • Project List: Select from available projects
  • Task List: Select from available tasks
  • Organization Contact List: Select from available clients/contacts
  • Organization Team List: Select from available teams

Prerequisites

Before setting up the Zapier integration, ensure you have:

  1. Gauzy Instance: A running Gauzy server
  2. Zapier Account: A Zapier account (free or paid)
  3. Zapier Developer Account: Access to Zapier Developer Platform for custom integrations
  4. Environment Configuration: Proper environment variables configured

Setup Instructions

1. Environment Configuration

Configure the following environment variables in your Gauzy instance:

# Zapier OAuth Configuration
GAUZY_ZAPIER_ALLOWED_DOMAINS=gauzy.co,*.gauzy.co,ever.co,*.ever.co,zapier.com,*.zapier.com,localhost
GAUZY_ZAPIER_CLIENT_ID=your_zapier_client_id
GAUZY_ZAPIER_CLIENT_SECRET=your_zapier_client_secret
GAUZY_ZAPIER_REDIRECT_URL="${API_BASE_URL}/api/integration/zapier/oauth/callback"
GAUZY_ZAPIER_POST_INSTALL_URL="${CLIENT_BASE_URL}/#/pages/integrations/zapier"
# Maximum number of OAuth authorization codes to store in memory
GAUZY_ZAPIER_MAX_AUTH_CODES=1000
# Number of server instances (affects auth code cleanup behavior)
GAUZY_ZAPIER_INSTANCE_COUNT=1

# API Configuration
API_BASE_URL=http://localhost:3000
CLIENT_BASE_URL=http://localhost:4200

Then, configure these following in the environment of your Zapier dashboard:

ACCESS_TOKEN=YOUR_ACCESS_TOKEN
REFRESH_TOKEN=YOUR_REFRESH_TOKEN
CLIENT_ID=your-zapier-client-id
CLIENT_SECRET=your-zapier-client-secret
API_BASE_URL=http://localhost:3000
APP_NAME=Gauzy

2. Build the Plugin

The Zapier integration plugin should be automatically included in your Gauzy installation. If you need to build it manually run:

yarn build:package:plugin:integration-zapier

and for Zapier UI integration

yarn build:package:plugin:integration-zapier-ui

3. Create Zapier Application

Step 1: Access Zapier Developer Platform

  1. Go to Zapier Developer Platform
  2. Sign in with your Zapier account
  3. Click "Create New Integration"

Step 2: Basic Integration Setup

  1. Integration Name: Enter "Gauzy" or your preferred name
  2. Description: "Time tracking and project management integration"
  3. Logo: Upload your Gauzy/company logo (optional)
  4. Website: Your Gauzy instance URL

Step 3: Configure Authentication

  1. Navigate to Authentication section
  2. Choose OAuth v2 as authentication type
  3. Configure the following URLs:
Authorization URL: http://localhost:3000/api/integration/zapier/oauth/authorize
Access Token Request URL: http://localhost:3000/api/integration/zapier/token
Refresh Token Request URL: http://localhost:3000/api/integration/zapier/refresh-token
  1. Set up Scopes: zap zap:write authentication
  2. Add Test Request:
    • URL: http://localhost:3000/api/auth/authenticated
    • Method: GET

Step 4: Create Triggers and Actions

Timer Status Trigger:

  1. Navigate to Triggers section
  2. Create new trigger with key: timer_status
  3. Configure as REST Hook trigger
  4. Set webhook subscription URLs:
    • Subscribe: POST /api/integration/zapier/webhooks
    • Unsubscribe: DELETE /api/integration/zapier/webhooks/{id}

Start Timer Action:

  1. Navigate to Actions section
  2. Create new action with key: start_timer
  3. Configure input fields for timer parameters
  4. Set API endpoint: POST /api/timesheet/timer/start

Stop Timer Action:

  1. Create another action with key: stop_timer
  2. Configure input fields
  3. Set API endpoint: POST /api/timesheet/timer/stop

4. Deploy and Test

  1. Deploy your Zapier integration
  2. Test the authentication flow
  3. Verify triggers and actions work correctly
  4. Invite team members to test (optional)

How It Works

Authentication Flow

  1. User Authorization: User connects their Gauzy account in Zapier
  2. OAuth Handshake: Standard OAuth2 authorization code flow
  3. Token Exchange: Authorization code exchanged for access token
  4. Token Storage: Zapier securely stores access and refresh tokens
  5. API Access: Subsequent API calls use Bearer token authentication
sequenceDiagram
    participant U as User
    participant Z as Zapier
    participant G as Gauzy

    U->>Z: Connect Gauzy Account
    Z->>G: Redirect to /oauth/authorize
    G->>U: Show authorization page
    U->>G: Grant permission
    G->>Z: Return authorization code
    Z->>G: Exchange code for tokens
    G->>Z: Return access & refresh tokens
    Z->>Z: Store tokens securely
Loading

Webhook Integration

The integration uses REST hooks for real-time notifications:

  1. Subscription: Zapier subscribes to specific events via webhook API
  2. Event Detection: Gauzy detects timer events (start, stop, status change)
  3. Notification: Gauzy sends HTTP POST to registered webhook URLs
  4. Processing: Zapier receives and processes the webhook payload
  5. Zap Execution: Configured Zap actions are triggered

Event Handling

Timer Events are handled by dedicated event handlers:

  • TimerStartedHandler: Captures timer start events
  • TimerStoppedHandler: Captures timer stop events
  • TimerStatusUpdatedHandler: Captures timer status changes

Each handler formats the event data and broadcasts to subscribed webhooks.

Configuration Examples

Example 1: Slack Notification on Timer Start

Trigger: Timer Status Changed (Gauzy) Action: Send Channel Message (Slack)

When: Timer status changes to "started"
Do: Send message to #time-tracking channel
Message: "{{employee_name}} started working on {{project_name}} - {{task_name}}"

Example 2: Create Trello Card on Timer Stop

Trigger: Timer Status Changed (Gauzy) Action: Create Card (Trello)

When: Timer status changes to "stopped"
Do: Create card in "Completed Work" list
Title: "{{description}} - {{duration}} minutes"
Description: "Project: {{project_name}}\nTask: {{task_name}}\nTime: {{duration}} minutes"

Example 3: Start Timer from Google Calendar

Trigger: Event Start (Google Calendar) Action: Start Timer (Gauzy)

When: Calendar event starts
Do: Start timer in Gauzy
Description: "{{event_title}}"
Project: "{{event_location}}" (mapped to project name)

API Endpoints

The Zapier integration exposes the following API endpoints:

Authentication Endpoints

  • GET /api/integration/zapier/oauth/authorize - OAuth authorization endpoint
  • POST /api/integration/zapier/token - Token exchange endpoint
  • POST /api/integration/zapier/refresh-token - Token refresh endpoint
  • GET /api/auth/authenticated - Authentication test endpoint

Webhook Management

  • POST /api/integration/zapier/webhooks - Create webhook subscription
  • DELETE /api/integration/zapier/webhooks/{id} - Delete webhook subscription

Timer Management

  • GET /api/timesheet/timer/status - Get current timer status
  • GET /api/timesheet/timer/status/worked - Get timer history
  • POST /api/timesheet/timer/start - Start a new timer
  • POST /api/timesheet/timer/stop - Stop running timer

Dynamic Data Sources

  • GET /api/tenant - List available tenants
  • GET /api/organization - List available organizations
  • GET /api/organization-project - List available projects
  • GET /api/tasks - List available tasks
  • GET /api/organization-contact - List available contacts
  • GET /api/organization-team - List available teams

Testing the Integration

1. Test Authentication

  1. In Zapier, create a new Zap
  2. Choose Gauzy as the trigger app
  3. Select "Timer Status Changed" trigger
  4. Click "Connect an account"
  5. Complete the OAuth flow
  6. Verify connection shows your Gauzy user information

2. Test Timer Status Trigger

  1. Configure the Timer Status trigger in your Zap
  2. Add a simple action (e.g., send email)
  3. Test the trigger:
    • Start a timer in Gauzy
    • Check if the trigger fires in Zapier
    • Verify the data payload contains expected fields

3. Test Start Timer Action

  1. Create a Zap with any trigger
  2. Add "Start Timer" action for Gauzy
  3. Configure required fields:
    • Tenant ID
    • Organization ID
    • Description
    • Project (optional)
    • Task (optional)
  4. Test the action and verify timer starts in Gauzy

4. Test Stop Timer Action

  1. Ensure you have a running timer in Gauzy
  2. Create a Zap with "Stop Timer" action
  3. Test the action and verify timer stops

Troubleshooting

Common Issues

1. Authentication Failures

Error: "Invalid client credentials"

Solution:

  • Verify GAUZY_ZAPIER_CLIENT_ID and GAUZY_ZAPIER_CLIENT_SECRET are set correctly
  • Check that OAuth URLs in Zapier match your API endpoints
  • Ensure API_BASE_URL environment variable is correct

2. Webhook Not Triggering

Trigger not firing when timer events occur

Solution:

  • Verify webhook subscription was created successfully
  • Check Gauzy logs for webhook delivery attempts
  • Ensure timer events are being captured by event handlers
  • Test webhook URL manually with curl/Postman

3. Dynamic Dropdowns Not Loading

Error: "Could not load choices"

Solution:

  • Verify authentication token has proper scopes
  • Check API endpoints for tenant, organization, project data
  • Ensure user has access to the requested resources

4. Timer Actions Failing

Error: "Failed to start/stop timer"

Solution:

  • Verify required fields are provided (tenantId, organizationId)
  • Check user permissions for timer management
  • Ensure project/task IDs are valid (if provided)
  • Review API error logs for specific error details

Debug Steps

  1. Check Integration Status:
# Test authentication
curl -H "Authorization: Bearer YOUR_TOKEN" \
     http://localhost:3000/api/auth/authenticated
  1. Test Webhook Subscription:
# Create test subscription
curl -X POST http://localhost:3000/api/integration/zapier/webhooks \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"target_url": "https://hooks.zapier.com/hooks/catch/xxx/", "event": "timer.status.changed"}'
  1. Verify Event Handlers:
  • Check server logs for event handler execution
  • Verify webhook delivery attempts in logs
  • Test timer events manually in Gauzy UI
  1. Test API Endpoints:
# Test timer status
curl -H "Authorization: Bearer YOUR_TOKEN" \
     http://localhost:3000/api/timesheet/timer/status

# Test start timer
curl -X POST http://localhost:3000/api/timesheet/timer/start \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"tenantId": "xxx", "organizationId": "xxx", "description": "Test timer"}'

Security Considerations

Token Security

  • Secure Storage: OAuth tokens are stored securely by Zapier
  • Token Refresh: Access tokens are automatically refreshed when expired
  • Scope Limitation: Tokens have limited scopes (zap, zap:write, authentication)

Webhook Security

  • HTTPS Only: All webhook URLs must use HTTPS
  • URL Validation: Webhook URLs are validated to prevent SSRF attacks
  • Private IP Blocking: Private IP addresses blocked in production
  • Tenant Isolation: Webhook subscriptions are isolated by tenant

API Security

  • Bearer Authentication: All API calls require valid Bearer tokens
  • Tenant Context: API operations are scoped to authenticated user's tenant
  • Rate Limiting: API endpoints are rate-limited to prevent abuse
  • Input Validation: All input parameters are validated and sanitized

Advanced Configuration

Custom Event Types

You can extend the integration to support additional event types:

  1. Create Event Handler:
@EventsHandler(CustomEvent)
export class CustomEventHandler implements IEventHandler<CustomEvent> {
  constructor(private readonly zapierWebhookService: ZapierWebhookService) {}

  async handle(event: CustomEvent): Promise<void> {
    await this.zapierWebhookService.notifyCustomEvent(event.data);
  }
}
  1. Add Trigger Definition:
// In zapier/src/triggers/customEvent.ts
export default {
  key: 'custom_event',
  noun: 'Custom Event',
  display: {
    label: 'Custom Event Trigger',
    description: 'Triggers when custom event occurs'
  },
  operation: {
    type: 'hook',
    performSubscribe: subscribe,
    performUnsubscribe: unsubscribe,
    sample: { /* sample data */ }
  }
};

Organization-Level Settings

The integration supports organization-level configuration:

// Filter subscriptions by organization
const subscriptions = await this.zapierWebhookSubscriptionRepository.find({
  where: {
    event: 'timer.status.changed',
    tenantId,
    organizationId // Filter by specific organization
  }
});

Custom Field Mapping

Configure custom fields for webhook payloads:

// Add custom fields to timer webhook data
const webhookData = {
  ...standardTimerData,
  customField1: timer.customField1,
  customField2: timer.customField2,
  // Include organization-specific metadata
  organizationSettings: organizationConfig
};

Performance Optimization

Webhook Delivery

  • Concurrent Delivery: Webhooks are delivered concurrently using Promise.all()
  • Error Handling: Individual webhook failures don't affect other deliveries
  • Timeout Configuration: HTTP timeouts prevent hanging requests
  • Retry Logic: Consider implementing retry logic for failed deliveries

Database Optimization

  • Indexing: Webhook subscriptions are indexed by event, tenant, and organization
  • Connection Pooling: Database connections are pooled for efficiency
  • Query Optimization: Efficient queries to find matching subscriptions

Monitoring and Analytics

Logging

The integration provides comprehensive logging:

// Webhook delivery logging
this.logger.log(`Timer ${eventType} event sent to Zapier webhook for tenant ${tenantId}`);

// Error logging
this.logger.error(`Failed to notify webhook ${sub.id} at ${sub.targetUrl}`, error);

// Subscription management logging
this.logger.log(`Successfully created webhook subscription with id ${subscription.id}`);

Metrics to Monitor

  • Authentication Success Rate: Track OAuth flow completion rates
  • Webhook Delivery Success Rate: Monitor webhook delivery failures
  • API Response Times: Track performance of timer and data endpoints
  • Error Rates: Monitor and alert on integration errors
  • Usage Patterns: Track most used triggers and actions

Migration and Upgrades

Version Compatibility

The integration follows semantic versioning:

  • Major: Breaking changes to API or webhook payloads
  • Minor: New features, triggers, or actions
  • Patch: Bug fixes and improvements

Upgrade Procedures

  1. Review changelog for breaking changes
  2. Update environment variables if needed
  3. Test authentication flow after upgrade
  4. Verify webhook subscriptions still work
  5. Update Zapier integration if API changes occurred

Support and Resources

Documentation

Source Code

  • Plugin Source: packages/plugins/integration-zapier/
  • Zapier App Code: packages/plugins/integration-zapier/zapier/
  • GitHub Repository: ever-co/ever-gauzy

For issues and feature requests, please visit the GitHub Issues page.

Clone this wiki locally