Overview

The Webhooks API allows you to create subscriptions to be notified about modifications made to your workspace entities.

General characteristics

• A user may define one or more Webhooks subscriptions per workspace.
• Each subscription may have different filters to receive notifications about a sub-set of events for supported entities.
• The visibility access of the subscription's creator will be taken into account to filter out events that the creator has no access to. Example: being notified about other users time entry changes if the creator is not an administrator of the workspace.
• The URL endpoint configured for a subscription must be both reachable and return a 2xx HTTP status code.
• A subscription must be both enabled and validated before events are sent to its corresponding URL endpoint.
• The Webhooks API base URL is https://api.track.toggl.com/webhooks/api/v1.

Glossary

Common used terms across Webhooks documents

• Event Filter: allows you to specify which events a given subscription should receive in its configured URL callback. A subscription may have multiple event filters, but must have at least one.
• Subscription: a Webhooks subscription is an entity tied to a single workspace and user creator that has a description, a secret, a set of event filters, a url callback and an enabled and validation status. A user may have multiple subscriptions and a workspace may have multiple subscriptions from different users, but there's a limit of subscriptions per user and workspace.
• URL callback: is the URL destination endpoint for a subscription. The system will validate that it's both reachable and returns a 2xx status before starting to forward events to it.
• User Creator: given a subscription, the user creator is the one who set it up. Any event sent to the configured url callback will be validated using the permissions of this user. If the user creator doesn't have permission to see some entity, then events related to that entity won't be forwarded to the URL callback. A workspace administrator may list and edit subscriptions from other users in that workspace.
• Validation Status: each created subscription must be validated before it can start receiving events. This validation step is to ensure that the creator has access to the provided URL callback. Otherwise, it would mean that Toggl is sending unsolicited events to the configured URL. A non-validated and not enabled subscription may still receive the special PING event which is useful to test that you can receive events from Toggl.