How to Track Time with Toggl 2026 and Clockify 5.0 for Freelance Developers

// toggl-client.js
// Complete Toggl 2026 API v3 Client with retry logic, rate limit handling, and structured logging
import axios from 'axios';
import pino from 'pino';
import dotenv from 'dotenv';
import { setTimeout } from 'timers/promises';

dotenv.config();

const logger = pino({
  transport: {
    target: 'pino-pretty',
    options: { colorize: true }
  },
  level: process.env.LOG_LEVEL || 'info'
});

const TOGGL_API_BASE = 'https://api.toggl.com/v3';

const RETRY_CONFIG = {
  maxRetries: 3,
  baseDelayMs: 1000,
  retryableStatuses: [429, 500, 502, 503, 504]
};

class TogglAPIError extends Error {
  constructor(message, statusCode, responseData) {
    super(message);
    this.name = 'TogglAPIError';
    this.statusCode = statusCode;
    this.responseData = responseData;
    this.retryable = RETRY_CONFIG.retryableStatuses.includes(statusCode);
  }
}

const createTogglClient = () => {
  const apiKey = process.env.TOGGL_API_KEY;
  if (!apiKey) {
    logger.fatal('TOGGLE_API_KEY environment variable is not set');
    process.exit(1);
  }

  const client = axios.create({
    baseURL: TOGGL_API_BASE,
    auth: {
      username: apiKey,
      password: 'api_token'
    },
    headers: {
      'Content-Type': 'application/json',
      'User-Agent': 'Freelance-Time-Sync/1.0 (contact@yourdomain.com)'
    },
    timeout: 5000
  });

  client.interceptors.response.use(
    (response) => response,
    async (error) => {
      const status = error.response?.status;
      const retryable = RETRY_CONFIG.retryableStatuses.includes(status);

      if (retryable && error.config.__retryCount < RETRY_CONFIG.maxRetries) {
        error.config.__retryCount = error.config.__retryCount || 0;
        error.config.__retryCount += 1;

        const delay = RETRY_CONFIG.baseDelayMs * Math.pow(2, error.config.__retryCount) + Math.random() * 1000;
        logger.warn(`Retrying Toggl request (attempt ${error.config.__retryCount}/${RETRY_CONFIG.maxRetries}) after ${delay}ms`, {
          url: error.config.url,
          status
        });

        await setTimeout(delay);
        return client(error.config);
      }

      throw new TogglAPIError(
        `Toggl API request failed: ${error.message}`,
        status,
        error.response?.data
      );
    }
  );

  return client;
};

export const getTimeEntries = async (workspaceId, startDate, endDate) => {
  const client = createTogglClient();
  const start = startDate.toISOString();
  const end = endDate.toISOString();

  logger.info(`Fetching Toggl time entries for workspace ${workspaceId}`, { start, end });

  try {
    const response = await client.get(`/workspaces/${workspaceId}/time_entries`, {
      params: {
        start_date: start,
        end_date: end,
        per_page: 100
      }
    });

    logger.info(`Fetched ${response.data.length} time entries from Toggl`);
    return response.data;
  } catch (error) {
    logger.error('Failed to fetch Toggl time entries', { error: error.message, status: error.statusCode });
    throw error;
  }
};

export const createTimeEntry = async (workspaceId, entryData) => {
  const client = createTogglClient();

  logger.info(`Creating Toggl time entry in workspace ${workspaceId}`, { description: entryData.description });

  try {
    const response = await client.post(`/workspaces/${workspaceId}/time_entries`, entryData);
    logger.info(`Created Toggl time entry ${response.data.id}`);
    return response.data;
  } catch (error) {
    logger.error('Failed to create Toggl time entry', { error: error.message, entryData });
    throw error;
  }
};

// clockify-sync.js
// Clockify 5.0 API v2 Client and Toggl-to-Clockify sync logic with idempotency and conflict resolution
import axios from 'axios';
import pino from 'pino';
import dotenv from 'dotenv';
import { createHash } from 'crypto';
import { setTimeout } from 'timers/promises';
import { getTimeEntries as getTogglEntries } from './toggl-client.js';

dotenv.config();

const logger = pino({
  transport: { target: 'pino-pretty', options: { colorize: true } },
  level: process.env.LOG_LEVEL || 'info'
});

const CLOCKIFY_API_BASE = 'https://api.clockify.me/v2';
const RETRY_CONFIG = {
  maxRetries: 3,
  baseDelayMs: 1000,
  retryableStatuses: [429, 500, 502, 503, 504]
};

class ClockifyAPIError extends Error {
  constructor(message, statusCode, responseData, idempotencyKey) {
    super(message);
    this.name = 'ClockifyAPIError';
    this.statusCode = statusCode;
    this.responseData = responseData;
    this.idempotencyKey = idempotencyKey;
    this.retryable = RETRY_CONFIG.retryableStatuses.includes(statusCode);
  }
}

const generateIdempotencyKey = (entry) => {
  return createHash('sha256')
    .update(`${entry.id}-${entry.workspace_id}`)
    .digest('hex');
};

const createClockifyClient = () => {
  const apiKey = process.env.CLOCKIFY_API_KEY;
  if (!apiKey) {
    logger.fatal('CLOCKIFY_API_KEY environment variable is not set');
    process.exit(1);
  }

  const client = axios.create({
    baseURL: CLOCKIFY_API_BASE,
    headers: {
      'X-Api-Key': apiKey,
      'Content-Type': 'application/json',
      'User-Agent': 'Freelance-Time-Sync/1.0 (contact@yourdomain.com)'
    },
    timeout: 5000
  });

  client.interceptors.response.use(
    (response) => response,
    async (error) => {
      const status = error.response?.status;
      if (RETRY_CONFIG.retryableStatuses.includes(status) && error.config.__retryCount < RETRY_CONFIG.maxRetries) {
        error.config.__retryCount = error.config.__retryCount || 0;
        error.config.__retryCount += 1;
        const delay = RETRY_CONFIG.baseDelayMs * Math.pow(2, error.config.__retryCount) + Math.random() * 1000;
        logger.warn(`Retrying Clockify request (attempt ${error.config.__retryCount}/${RETRY_CONFIG.maxRetries})`, {
          url: error.config.url,
          status
        });
        await setTimeout(delay);
        return client(error.config);
      }
      throw new ClockifyAPIError(
        `Clockify API request failed: ${error.message}`,
        status,
        error.response?.data,
        error.config.headers?.['Idempotency-Key']
      );
    }
  );

  return client;
};

const mapTogglProjectToClockify = (togglProjectId) => {
  const mapping = {
    'toggl-proj-123': 'clockify-proj-456',
    'toggl-proj-789': 'clockify-proj-012',
    'toggl-proj-345': 'clockify-proj-678'
  };
  return mapping[togglProjectId] || process.env.DEFAULT_CLOCKIFY_PROJECT_ID;
};

export const syncTogglEntryToClockify = async (togglEntry, clockifyWorkspaceId) => {
  const client = createClockifyClient();
  const idempotencyKey = generateIdempotencyKey(togglEntry);
  const clockifyProjectId = mapTogglProjectToClockify(togglEntry.project_id);

  if (!clockifyProjectId) {
    logger.warn(`Skipping Toggl entry ${togglEntry.id}: no mapped Clockify project`, { togglEntry });
    return null;
  }

  const clockifyEntry = {
    start: togglEntry.start,
    end: togglEntry.stop,
    description: togglEntry.description,
    projectId: clockifyProjectId,
    billable: togglEntry.billable,
    tagIds: togglEntry.tags?.map(tag => tag.id) || []
  };

  logger.info(`Syncing Toggl entry ${togglEntry.id} to Clockify`, { idempotencyKey, clockifyWorkspaceId });

  try {
    const response = await client.post(
      `/workspaces/${clockifyWorkspaceId}/time-entries`,
      clockifyEntry,
      {
        headers: {
          'Idempotency-Key': idempotencyKey
        }
      }
    );

    logger.info(`Synced Toggl entry ${togglEntry.id} to Clockify entry ${response.data.id}`);
    return response.data;
  } catch (error) {
    if (error.statusCode === 409) {
      logger.info(`Toggl entry ${togglEntry.id} already synced to Clockify (idempotency key match)`);
      return null;
    }
    logger.error('Failed to sync Toggl entry to Clockify', { error: error.message, togglEntryId: togglEntry.id });
    throw error;
  }
};

export const batchSyncTimeEntries = async (togglWorkspaceId, clockifyWorkspaceId, startDate, endDate) => {
  const stats = { synced: 0, skipped: 0, failed: 0 };
  const togglEntries = await getTogglEntries(togglWorkspaceId, startDate, endDate);

  logger.info(`Starting batch sync of ${togglEntries.length} Toggl entries to Clockify`);

  for (const entry of togglEntries) {
    try {
      const result = await syncTogglEntryToClockify(entry, clockifyWorkspaceId);
      if (result) {
        stats.synced += 1;
      } else {
        stats.skipped += 1;
      }
    } catch (error) {
      stats.failed += 1;
      logger.error(`Failed to sync entry ${entry.id}`, { error: error.message });
    }
  }

  logger.info(`Batch sync complete`, stats);
  return stats;
};

// webhook-handler.js
// Express.js webhook handler for Toggl 2026 and Clockify 5.0 events with signature verification
import express from 'express';
import pino from 'pino';
import pinoHttp from 'pino-http';
import dotenv from 'dotenv';
import { syncTogglEntryToClockify } from './clockify-sync.js';
import { batchSyncTimeEntries } from './clockify-sync.js';

dotenv.config();

const logger = pino({
  transport: { target: 'pino-pretty', options: { colorize: true } },
  level: process.env.LOG_LEVEL || 'info'
});

const app = express();
const PORT = process.env.PORT || 3000;

app.use(pinoHttp({ logger }));

app.use(express.json({
  verify: (req, res, buf) => {
    req.rawBody = buf.toString();
  }
}));

const verifyTogglWebhookSignature = async (signature, rawBody) => {
  const webhookSecret = process.env.TOGGL_WEBHOOK_SECRET;
  if (!webhookSecret) {
    logger.fatal('TOGGLE_WEBHOOK_SECRET is not set');
    process.exit(1);
  }

  const crypto = await import('crypto');
  const hmac = crypto.createHmac('sha256', webhookSecret);
  hmac.update(rawBody);
  const expectedSignature = `sha256=${hmac.digest('hex')}`;

  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expectedSignature));
};

const verifyClockifyWebhookSignature = async (signature, rawBody) => {
  const webhookSecret = process.env.CLOCKIFY_WEBHOOK_SECRET;
  if (!webhookSecret) {
    logger.fatal('CLOCKIFY_WEBHOOK_SECRET is not set');
    process.exit(1);
  }

  const crypto = await import('crypto');
  const hmac = crypto.createHmac('sha256', webhookSecret);
  hmac.update(rawBody);
  const expectedSignature = hmac.digest('hex');

  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expectedSignature));
};

const handleTogglTimeEntryEvent = async (webhookEvent) => {
  const { event_type, time_entry, workspace_id } = webhookEvent;

  if (!['time_entry.created', 'time_entry.updated'].includes(event_type)) {
    logger.info(`Ignoring Toggl event type: ${event_type}`);
    return;
  }

  logger.info(`Processing Toggl event ${event_type} for entry ${time_entry.id}`);

  try {
    await syncTogglEntryToClockify(time_entry, process.env.CLOCKIFY_WORKSPACE_ID);
  } catch (error) {
    logger.error(`Failed to process Toggl webhook event`, { error: error.message, eventType: event_type });
    throw error;
  }
};

app.post('/webhooks/toggl', async (req, res) => {
  try {
    const signature = req.headers['x-toggl-signature'];
    if (!signature) {
      return res.status(401).json({ error: 'Missing Toggl signature header' });
    }

    const isValid = await verifyTogglWebhookSignature(signature, req.rawBody);
    if (!isValid) {
      logger.warn('Invalid Toggl webhook signature');
      return res.status(401).json({ error: 'Invalid signature' });
    }

    const event = req.body;
    await handleTogglTimeEntryEvent(event);

    res.status(200).json({ status: 'processed' });
  } catch (error) {
    logger.error('Toggl webhook handler failed', { error: error.message });
    res.status(500).json({ error: 'Internal server error' });
  }
});

app.post('/webhooks/clockify', async (req, res) => {
  try {
    const signature = req.headers['x-clockify-signature'];
    if (!signature) {
      return res.status(401).json({ error: 'Missing Clockify signature header' });
    }

    const isValid = await verifyClockifyWebhookSignature(signature, req.rawBody);
    if (!isValid) {
      logger.warn('Invalid Clockify webhook signature');
      return res.status(401).json({ error: 'Invalid signature' });
    }

    const event = req.body;
    logger.info(`Received Clockify event: ${event.eventType}`, { entryId: event.timeEntry?.id });

    res.status(200).json({ status: 'processed' });
  } catch (error) {
    logger.error('Clockify webhook handler failed', { error: error.message });
    res.status(500).json({ error: 'Internal server error' });
  }
});

app.get('/health', (req, res) => {
  res.status(200).json({ status: 'healthy', timestamp: new Date().toISOString() });
});

app.listen(PORT, () => {
  logger.info(`Webhook handler listening on port ${PORT}`);
});

export const handler = async (event) => {
  return {
    statusCode: 200,
    body: JSON.stringify({ status: 'processed' })
  };
};

// report-generator.js
import { getTimeEntries } from './toggl-client.js';
import yaml from 'js-yaml';
import fs from 'fs';
import { writeFileSync } from 'fs';

const loadConfig = () => yaml.load(fs.readFileSync('./config/client-rates.yaml', 'utf8'));

export const generateMonthlyTaxReport = async (workspaceId, year, month) => {
  const startDate = new Date(year, month - 1, 1);
  const endDate = new Date(year, month, 0);
  const entries = await getTimeEntries(workspaceId, startDate, endDate);
  const config = loadConfig();
  const report = [];

  const clientHours = {};
  entries.forEach(entry => {
    const projectId = entry.project_id;
    const client = config.projects[projectId]?.client || 'Uncategorized';
    const hours = entry.duration / 3600;
    const rate = config.projects[projectId]?.rate || 0;

    if (!clientHours[client]) {
      clientHours[client] = { totalHours: 0, totalRevenue: 0, rate: 0 };
    }
    clientHours[client].totalHours += hours;
    clientHours[client].totalRevenue += hours * rate;
    clientHours[client].rate = rate;
  });

  const csvLines = ['Client,Total Hours,Hourly Rate,Total Revenue,Self-Employment Tax'];
  Object.entries(clientHours).forEach(([client, data]) => {
    const tax = data.totalRevenue * 0.153;
    csvLines.push(`${client},${data.totalHours.toFixed(2)},${data.rate},${data.totalRevenue.toFixed(2)},${tax.toFixed(2)}`);
  });

  const csvContent = csvLines.join('\n');
  const fileName = `tax-report-${year}-${month}.csv`;
  writeFileSync(fileName, csvContent);
  console.log(`Generated report: ${fileName}`);
  return fileName;
};

time-sync-toggl-clockify/
├── config/
│   ├── project-mapping.yaml  # Toggl to Clockify project ID mappings
│   └── client-rates.yaml     # Client hourly rates and tax categories
├── src/
│   ├── toggl-client.js       # Toggl 2026 API v3 client
│   ├── clockify-sync.js      # Clockify 5.0 sync logic
│   ├── webhook-handler.js    # Express.js webhook handler
│   └── report-generator.js   # Tax report generation module
├── serverless.yml            # AWS Lambda deployment config
├── package.json              # Node.js dependencies
├── .env.example              # Example environment variables
└── README.md                 # Setup and deployment instructions

const generateIdempotencyKey = (entry) => {
  return createHash('sha256')
    .update(`${entry.id}-${entry.workspace_id}`)
    .digest('hex');
};

import promClient from 'prom-client';
const register = new promClient.Registry();
const rateLimitRemaining = new promClient.Gauge({
  name: 'toggl_rate_limit_remaining',
  help: 'Remaining Toggl API requests per minute',
  labelNames: ['workspace_id']
});
register.registerMetric(rateLimitRemaining);

import yaml from 'js-yaml';
import fs from 'fs';
const loadProjectMapping = () => {
  try {
    return yaml.load(fs.readFileSync('./config/project-mapping.yaml', 'utf8'));
  } catch (error) {
    logger.fatal('Failed to load project mapping config', { error: error.message });
    process.exit(1);
  }
};