Event

trigger.toggl_event

TriggerBusiness appsconnection requiredruns in-engine

Registers a Toggl Track webhooks subscription on publish, answers Toggl's validation ping, and starts one run per delivered event, verified against Toggl's HMAC-SHA256 signature.

Start a run when something changes in a Toggl Track workspace — a time entry, project, client, task or tag. Publishing creates a webhooks subscription in the tenant's own workspace; disabling or unpublishing deletes it.

Ask about Toggl Track All Toggl Track nodes

Connection

Required: Yes — the node will not save without one
Auth type: Username & password
Providers: Toggl Track
Secret shape: the Toggl Track API token
Resolved by: config.connection_id, else node.connection_id
Note: The token's owner must be able to see the events being subscribed to — Toggl filters deliveries by the subscription creator's workspace permissions, so a non-admin token silently receives fewer events than the filters ask for. Publishing also needs MANTLE_APP_PUBLIC_BASE_URL set to an https URL Toggl can reach.

Configuration

2 fields, 1 required. A dotted path is a nested object and name[] an array of objects — the editor renders the same tree.

Field	Type	Required	Default	Constraints	Example
workspace_id The numeric id of the Toggl workspace to watch — subscriptions, and their plan limits, are per workspace. Find it in the Toggl URL or with the toggl.list_workspaces node.	string	Yes	—	matches ^\d+$	1234567
events Which changes to subscribe to, as entity.action — e.g. time_entry.created. Either half may be "", so project. is every project change and . is everything in the workspace (noisy: each one starts a run, and Toggl caps events per subscription by plan).	array	No	["time_entry.created"]	1–64 characters; array of string	—

Example configuration

Every value below is the contract’s own example or default — nothing invented.

{
  "events": [
    "time_entry.created"
  ],
  "workspace_id": "1234567"
}

Output

One shape.

toggl event

Toggl's event envelope, flattened. payload and metadata vary by entity, so the shape is open below the declared fields.

Extra keys beyond the ones listed can appear.

Field	Type	Example
id Toggl's event_id. Also the idempotency key: Toggl retries a delivery it did not get a 2xx for, and the retry carries this same id, so it joins the run it already started instead of starting a second. The ingress remembers a key for 24 hours.	string	8412
entity The Toggl entity the event is about — time_entry, project, tag… Read out of Toggl's metadata, whose schema Toggl does not publish, so it is empty when the delivery does not carry it.	string	time_entry
action created, updated or deleted, from the same metadata and with the same caveat as entity.	string	created
creator_id The Toggl user whose change raised the event.	number	—
subscription_id The Toggl subscription that delivered it — the one this trigger created.	number	—
created_at When Toggl recorded the event, ISO-8601 UTC.	string	2024-05-30T12:00:00.000000Z
timestamp When Toggl sent THIS delivery — it moves on every retry, while created_at does not. Compare it with now to spot a replay of a captured delivery.	string	2024-05-30T12:00:00.100000Z
url_callback The subscription URL Toggl believed it was delivering to. Toggl documents it as a cross-subscription forwarding check.	string	—
metadata Toggl's own metadata about the change (request_type, event_user_id, the entity and action keys, workspace and project ids). Toggl publishes no schema for it, which is why this shape is open.	object	—
payload The changed entity itself, in the shape Toggl's Track API returns it — a time entry, a project, a tag. Its keys depend on entity.	object	—

{
  "action": "created",
  "created_at": "2024-05-30T12:00:00.000000Z",
  "creator_id": 6,
  "entity": "time_entry",
  "id": "8412",
  "metadata": {
    "action": "created",
    "event_user_id": 6,
    "model": "time_entry",
    "request_type": "POST",
    "workspace_id": 1234567
  },
  "payload": {
    "description": "Ship 2.1",
    "duration": -1,
    "id": 3350123456,
    "project_id": 987654,
    "start": "2024-05-30T11:00:00Z",
    "workspace_id": 1234567
  },
  "subscription_id": 42,
  "timestamp": "2024-05-30T12:00:00.100000Z",
  "url_callback": "https://mantle.example/api/v1/hooks/p/acme/1f2e"
}

Notes

Publishing creates the subscription in Toggl; unpublishing, disabling or archiving deletes it. A workflow that is off is off at Toggl too.
Toggl limits subscriptions per workspace by plan — 1 on Free, 2 on Starter, 3 on Premium — and caps how many events each may carry. A publish over the limit is refused with Toggl's own message.
Toggl validates the callback by posting a ping and reading its own validation_code back; Mantle answers that automatically, and no run is started for it.
Each delivery is verified against an HMAC-SHA256 of the raw body under a secret Mantle mints per subscription.

Related Toggl Track nodes

See Event run in a workflow.

In a technical demo we add the Toggl Track connection, drop the node on the canvas and let Workflow Health pre-flight it before the first real run.

Book a technical demo Talk to sales