n8n-nodes-toggl

This is an n8n community node that provides integration with Toggl Track time tracking service. It lets you use Toggl Track in your n8n workflows.

Toggl Track is a popular time tracking application used by individuals and teams to track time spent on various projects and tasks.

Installation

Follow the installation guide in the n8n community nodes documentation.

Community Nodes (Recommended)

1. Go to Settings > Community Nodes.
2. Select Install.
3. Enter n8n-nodes-toggl in Enter npm package name.
4. Agree to the risks of using community nodes.
5. Select Install.

After installation, you'll find the Toggl and Toggl Webhook Trigger nodes in the nodes panel.

Manual Installation

To get started with development:

# Clone the repository
git clone https://github.com/example/n8n-nodes-toggl.git
cd n8n-nodes-toggl

# Install dependencies
pnpm install

# Build the nodes
pnpm build

# Link to n8n
cd ~/.n8n/nodes
ln -s /path/to/n8n-nodes-toggl/dist/nodes/Toggl n8n-nodes-toggl

Credentials

You need to set up Toggl API credentials to use this node:

Toggl API Token

1. Go to your Toggl Profile settings.
2. Scroll down to the API Token section.
3. Copy your API token.
4. In n8n, create new Toggl API credentials.
5. Paste your API token in the API Token field.

Compatibility

This node requires n8n version 0.187.0 or later.

Usage

Toggl Node

The Toggl node supports the following operations:

Time Entry Operations

• Start Time Entry: Start a new time entry with optional project and tags
• Stop Time Entry: Stop a running time entry (by ID or current)
• Get Current Time Entry: Retrieve the currently running time entry
• List Time Entries: Get time entries with date filtering and pagination

Project Operations

• Create Project: Create a new project in a workspace
• List Projects: Get projects from a workspace with optional archived filter

Client Operations

• Create Client: Create a new client in a workspace with optional external reference and notes
• List Clients: Get clients from a workspace with status filtering (active, archived, both) and name filtering

Raw Request

• Raw Request: Make custom API calls to any Toggl endpoint

Toggl Webhook Trigger

The webhook trigger node allows you to receive real-time notifications when events occur in Toggl:

• Project Events: created, updated, deleted
• Time Entry Events: created, updated, deleted
• Task Events: created, updated, deleted

The webhook trigger automatically:

• Creates webhook subscriptions with Toggl
• Validates webhook signatures for security
• Manages subscription lifecycle (create/delete)

Sample Workflow

Here's a sample workflow that starts a time entry when a new task is created in another system:

{
  "meta": {
    "instanceId": "example"
  },
  "nodes": [
    {
      "parameters": {},
      "name": "Start",
      "type": "n8n-nodes-base.start",
      "typeVersion": 1,
      "position": [240, 300],
      "id": "start-node"
    },
    {
      "parameters": {
        "resource": "timeEntry",
        "operation": "startTimeEntry",
        "description": "Working on {{$json.task_name}}",
        "projectId": "={{$json.project_id}}",
        "tags": "automated,n8n"
      },
      "name": "Start Toggl Timer",
      "type": "n8n-nodes-toggl.toggl",
      "typeVersion": 1,
      "position": [460, 300],
      "id": "toggl-node",
      "credentials": {
        "togglApi": {
          "id": "1",
          "name": "Toggl API"
        }
      }
    }
  ],
  "connections": {
    "Start": {
      "main": [
        [
          {
            "node": "Start Toggl Timer",
            "type": "main",
            "index": 0
          }
        ]
      ]
    }
  }
}

Webhook Workflow Example

Here's a workflow that triggers when a time entry is created in Toggl:

{
  "meta": {
    "instanceId": "example"
  },
  "nodes": [
    {
      "parameters": {
        "workspaceId": 123456,
        "events": ["time_entry:created", "time_entry:updated"],
        "description": "n8n automation webhook"
      },
      "name": "Toggl Webhook",
      "type": "n8n-nodes-toggl.togglWebhookTrigger",
      "typeVersion": 1,
      "position": [240, 300],
      "id": "webhook-trigger",
      "credentials": {
        "togglApi": {
          "id": "1",
          "name": "Toggl API"
        }
      },
      "webhookId": "webhook-id"
    },
    {
      "parameters": {
        "options": {}
      },
      "name": "Process Time Entry",
      "type": "n8n-nodes-base.function",
      "typeVersion": 1,
      "position": [460, 300],
      "id": "function-node"
    }
  ],
  "connections": {
    "Toggl Webhook": {
      "main": [
        [
          {
            "node": "Process Time Entry",
            "type": "main",
            "index": 0
          }
        ]
      ]
    }
  }
}

Common Use Cases

1. Project Management Integration: Automatically start/stop timers when tasks change status
2. Reporting: Extract time tracking data for custom reports and dashboards
3. Team Coordination: Send notifications when team members start/stop work
4. Billing Automation: Generate invoices based on tracked time
5. Productivity Monitoring: Track and analyze work patterns

API Reference

This node uses the Toggl Track API v9. All operations support the same parameters and return the same data structures as the official API.

Rate Limiting

The node automatically handles Toggl's rate limiting (429 responses) with exponential backoff retry logic.

Error Handling

API errors are properly wrapped and include helpful error messages. Enable "Continue on Fail" in node settings to handle errors gracefully in your workflows.

Development

Building

pnpm build

Testing

pnpm test

Linting

pnpm lint
pnpm lintfix

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass and linting is clean
6. Submit a pull request

License

MIT

Resources

• n8n community nodes documentation
• Toggl Track API documentation
• Toggl Track website

Support

For questions about this node, please open an issue on GitHub.

For general n8n support, visit the n8n community forum.