Skip to main content

Subscriptions

GET Retrieves existing subscriptions for the requested workspace ID.​

https://api.track.toggl.com/webhooks/api/v1/subscriptions/{workspace_id}

Retrieves existing subscriptions for the requested workspace ID.

curl  https://api.track.toggl.com/webhooks/api/v1/subscriptions/{workspace_id} \
-H "Content-Type: application/json"

Parameters​

Path​

nametyperequireddescription
workspace_idintegertrueNumeric ID of the workspace

Response​

200​

Array of:

nametypedescription
created_atstringTime of creation
deleted_atstringTime of deletion
descriptionstringDescription for this subscription, which is unique for its workspace
enabledbooleanWhether the subscription is enabled to notify events
event_filtersArray of
nametypedescription
actionstringType of modification applied to the business entity
entitystringToggl Track business entity to which this filter applies
List of filters to select events to notifiy
has_pending_eventsbooleanWhether there are events pending to be delivered to this subscription
secretstringAllows to validate whether the received events have been sent by Toggl
subscription_idintegerID of the Webhooks subscription
updated_atstringTime of last update
url_callbackstringURL endpoint where events will be notified
user_idintegerSubscription's creator ID
validated_atstringTime for when this subscription has been validated
workspace_idintegerSubscription's workspace ID

403​

User not found/accessible for workspace

500​

Internal Server Error

POST Creates a subscription.​

https://api.track.toggl.com/webhooks/api/v1/subscriptions/{workspace_id}

Creates a subscription for the requested workspace ID.

curl -X POST https://api.track.toggl.com/webhooks/api/v1/subscriptions/{workspace_id} \
-H "Content-Type: application/json" \
-d '{"created_at":"string","deleted_at":"string","description":"string","enabled":"boolean","event_filters":[{"action":"string","entity":"string"}],"has_pending_events":"boolean","secret":"string","subscription_id":"integer","updated_at":"string","url_callback":"string","user_id":"integer","validated_at":"string","workspace_id":"integer"}'

Parameters​

Path​

nametyperequireddescription
workspace_idintegertrueNumeric ID of the workspace

Body​

nametypedescription
created_atstringTime of creation
deleted_atstringTime of deletion
descriptionstringDescription for this subscription, which is unique for its workspace
enabledbooleanWhether the subscription is enabled to notify events
event_filtersArray of
nametypedescription
actionstringType of modification applied to the business entity
entitystringToggl Track business entity to which this filter applies
List of filters to select events to notifiy
has_pending_eventsbooleanWhether there are events pending to be delivered to this subscription
secretstringAllows to validate whether the received events have been sent by Toggl
subscription_idintegerID of the Webhooks subscription
updated_atstringTime of last update
url_callbackstringURL endpoint where events will be notified
user_idintegerSubscription's creator ID
validated_atstringTime for when this subscription has been validated
workspace_idintegerSubscription's workspace ID

Response​

200​

nametypedescription
created_atstringTime of creation
deleted_atstringTime of deletion
descriptionstringDescription for this subscription, which is unique for its workspace
enabledbooleanWhether the subscription is enabled to notify events
event_filtersArray of
nametypedescription
actionstringType of modification applied to the business entity
entitystringToggl Track business entity to which this filter applies
List of filters to select events to notifiy
has_pending_eventsbooleanWhether there are events pending to be delivered to this subscription
secretstringAllows to validate whether the received events have been sent by Toggl
subscription_idintegerID of the Webhooks subscription
updated_atstringTime of last update
url_callbackstringURL endpoint where events will be notified
user_idintegerSubscription's creator ID
validated_atstringTime for when this subscription has been validated
workspace_idintegerSubscription's workspace ID

400​

Possible error messages:

* URL endpoint {url_callback} responded with status {HTTP status code} instead of 200
* URL endpoint {url_callback} request failed with error: {HTTP error}
* User {user_id} already reached the limit of {allowed limit} enabled subscriptions for workspace {workspace_id}
* Subscription description must not be empty
* Subscription description '{description}' is already in use for workspace {workspace_id}
* The list of event filters must not be empty
* The limit of {allowed limit} event filters for your subscription has been exceeded as you're trying to set {number of filters} filters
* The following event filter appears more than once for your subscription: {subscription_id}
* The entity field for each subscription event filter must be non-empty
* The value '{entity}' for the filter entity can only contain letters, numbers and '_' or be '*' to match all entities
* The action field for each subscription event filter must be non-empty
* The value '{action}' for the filter action can only contain letters, numbers and '_' or be '*' to match all actions
* Invalid value '{action}' for event filter action

403​

User not found/accessible for workspace

500​

Internal Server Error

PUT Update existing subscription.​

https://api.track.toggl.com/webhooks/api/v1/subscriptions/{workspace_id}/{subscription_id}

Updates existing subscription given its ID and workspace ID.

curl -X PUT https://api.track.toggl.com/webhooks/api/v1/subscriptions/{workspace_id}/{subscription_id} \
-H "Content-Type: application/json" \
-d '{"created_at":"string","deleted_at":"string","description":"string","enabled":"boolean","event_filters":[{"action":"string","entity":"string"}],"has_pending_events":"boolean","secret":"string","subscription_id":"integer","updated_at":"string","url_callback":"string","user_id":"integer","validated_at":"string","workspace_id":"integer"}'

Parameters​

Path​

nametyperequireddescription
workspace_idintegertrueNumeric ID of the workspace
subscription_idintegertrueNumeric ID of the subscription

Body​

nametypedescription
created_atstringTime of creation
deleted_atstringTime of deletion
descriptionstringDescription for this subscription, which is unique for its workspace
enabledbooleanWhether the subscription is enabled to notify events
event_filtersArray of
nametypedescription
actionstringType of modification applied to the business entity
entitystringToggl Track business entity to which this filter applies
List of filters to select events to notifiy
has_pending_eventsbooleanWhether there are events pending to be delivered to this subscription
secretstringAllows to validate whether the received events have been sent by Toggl
subscription_idintegerID of the Webhooks subscription
updated_atstringTime of last update
url_callbackstringURL endpoint where events will be notified
user_idintegerSubscription's creator ID
validated_atstringTime for when this subscription has been validated
workspace_idintegerSubscription's workspace ID

Response​

200​

nametypedescription
created_atstringTime of creation
deleted_atstringTime of deletion
descriptionstringDescription for this subscription, which is unique for its workspace
enabledbooleanWhether the subscription is enabled to notify events
event_filtersArray of
nametypedescription
actionstringType of modification applied to the business entity
entitystringToggl Track business entity to which this filter applies
List of filters to select events to notifiy
has_pending_eventsbooleanWhether there are events pending to be delivered to this subscription
secretstringAllows to validate whether the received events have been sent by Toggl
subscription_idintegerID of the Webhooks subscription
updated_atstringTime of last update
url_callbackstringURL endpoint where events will be notified
user_idintegerSubscription's creator ID
validated_atstringTime for when this subscription has been validated
workspace_idintegerSubscription's workspace ID

400​

Possible error messages:

* URL endpoint {url_callback} responded with status {HTTP status code} instead of 2xx
* URL endpoint {url_callback} request failed with error: {HTTP error}
* User {user_id} already reached the limit of {allowed limit} enabled subscriptions for workspace {workspace_id}
* Subscription description must not be empty
* Subscription description '{description}' is already in use for workspace {workspace_id}
* The list of event filters must not be empty
* The limit of {allowed limit} event filters for your subscription has been exceeded as you're trying to set {number of filters} filters
* The following event filter appears more than once for your subscription: {event_filter}
* The entity field for each subscription event filter must be non-empty
* The value '{entity}' for the filter entity can only contain letters, numbers and '_' or be '*' to match all entities
* The action field for each subscription event filter must be non-empty
* The value '{action}' for the filter action can only contain letters, numbers and '_' or be '*' to match all actions
* Invalid value '{action}' for event filter action

403​

User not found/accessible for workspace

404​

subscription {subscription_id} for workspace {workspace_id} was not found

500​

Internal Server Error

DELETE Remove existing subscription.​

https://api.track.toggl.com/webhooks/api/v1/subscriptions/{workspace_id}/{subscription_id}

Remove existing subscription given its ID and workspace ID.

curl -X DELETE https://api.track.toggl.com/webhooks/api/v1/subscriptions/{workspace_id}/{subscription_id} \
-H "Content-Type: application/json"

Parameters​

Path​

nametyperequireddescription
workspace_idintegertrueNumeric ID of the workspace
subscription_idintegertrueNumeric ID of the subscription

Response​

200​

nametypedescription
created_atstringTime of creation
deleted_atstringTime of deletion
descriptionstringDescription for this subscription, which is unique for its workspace
enabledbooleanWhether the subscription is enabled to notify events
event_filtersArray of
nametypedescription
actionstringType of modification applied to the business entity
entitystringToggl Track business entity to which this filter applies
List of filters to select events to notifiy
has_pending_eventsbooleanWhether there are events pending to be delivered to this subscription
secretstringAllows to validate whether the received events have been sent by Toggl
subscription_idintegerID of the Webhooks subscription
updated_atstringTime of last update
url_callbackstringURL endpoint where events will be notified
user_idintegerSubscription's creator ID
validated_atstringTime for when this subscription has been validated
workspace_idintegerSubscription's workspace ID

403​

User not found/accessible for workspace

404​

subscription {subscription_id} for workspace {workspace_id} was not found

500​

Internal Server Error

PATCH Updates an existing subscription enabled status given its ID and workspace ID.​

https://api.track.toggl.com/webhooks/api/v1/subscriptions/{workspace_id}/{subscription_id}

Updates existing subscription enabled status.

curl -X PATCH https://api.track.toggl.com/webhooks/api/v1/subscriptions/{workspace_id}/{subscription_id} \
-H "Content-Type: application/json" \
-d '{"enabled":"boolean"}'

Parameters​

Path​

nametyperequireddescription
workspace_idintegertrueNumeric ID of the workspace
subscription_idintegertrueNumeric ID of the subscription

Body​

nametypedescription
enabledbooleanControls whether the subscription will be enabled or disabled

Response​

200​

nametypedescription
created_atstringTime of creation
deleted_atstringTime of deletion
descriptionstringDescription for this subscription, which is unique for its workspace
enabledbooleanWhether the subscription is enabled to notify events
event_filtersArray of
nametypedescription
actionstringType of modification applied to the business entity
entitystringToggl Track business entity to which this filter applies
List of filters to select events to notifiy
has_pending_eventsbooleanWhether there are events pending to be delivered to this subscription
secretstringAllows to validate whether the received events have been sent by Toggl
subscription_idintegerID of the Webhooks subscription
updated_atstringTime of last update
url_callbackstringURL endpoint where events will be notified
user_idintegerSubscription's creator ID
validated_atstringTime for when this subscription has been validated
workspace_idintegerSubscription's workspace ID

400​

Possible error messages:

* URL endpoint {url_callback} responded with status {HTTP status code} instead of 200
* URL endpoint {url_callback} request failed with error: {HTTP error}
* User {user_id} already reached the limit of {allowed limit} enabled subscriptions for workspace {workspace_id}

403​

User not found/accessible for workspace

404​

subscription {subscription_id} for workspace {workspace_id} was not found

500​

Internal Server Error
© 2024 Toggl. All rights reserved.