Skip to main content

Request Examples

We show practical examples on how to build requests to interact with the Webhooks API.

Notes:

  • the Webhooks API base URL is https://api.track.toggl.com/webhooks/api/v1,
  • we will be using cURL,
  • we will be parsing responses using jq,
  • in the examples you should replace {<variable>} with the corresponding value.

Request Parameters

The API expects the following parameters:

  • workspace_id: Required. The workspace ID for your webhooks subscription/s, to be provided in the URL path.
  • User-Agent: Suggested. The name of your application or your email address so we can get in touch in case you're doing something wrong. To be provided as a HTTP header.
  • Content-Type: Required (when applicable). The media type of the request body. To be provided as a HTTP header.

List available subscriptions for a given workspace

curl -u {api_token}:api_token \
-H 'User-Agent: {user_agent}' \
https://api.track.toggl.com/webhooks/api/v1/subscriptions/{workspace_id} | jq .

Create a subscription

curl -u {api_token}:api_token \
-X POST \
-d '{
"url_callback": "{url_callback}",
"event_filters": [
{"entity": "project", "action": "created"},
{"entity": "tag", "action": "*"}
],
"enabled": true,
"description": "My first Webhooks subscription"
}' \
-H 'User-Agent: {user_agent}' \
-H 'Content-Type: application/json' \
https://api.track.toggl.com/webhooks/api/v1/subscriptions/{workspace_id} | jq .

Response example:

{
"subscription_id": 1,
"workspace_id": {workspace_id},
"user_id": ...,
"enabled": true,
"description": "My first Webhooks subscription",
"event_filters": [
{
"entity": "project",
"action": "created"
},
{
"entity": "tag",
"action": "*"
}
],
"url_callback": {url_callback},
"validated_at": null,
"has_pending_events": false,
"created_at": "2022-05-31T02:50:45.984607Z"
}

Notes:

  • the {description} should be unique among all subscriptions for the given {workspace_id},
  • if the {secret} field is not provided an automatic secret will be generated,
  • replace {url_callback} with the URL endpoint that will receive request for this webhooks subscription,
  • after creating the subscription you still need to validate its url_callback,
  • to learn how to filter subscription events read about Event Filters,
  • read the API reference for the subscription creation endpoint.

Update a subscription

curl -u {api_token}:api_token \
-X PUT \
-d '{
"url_callback": "{url_callback}",
"event_filters": [
{"entity": "*", "action": "*"}
],
"enabled": true,
"secret": "new secret string",
"description": "My first Webhooks subscription"
}' \
-H 'User-Agent: {user_agent}' \
-H 'Content-Type: application/json' \
https://api.track.toggl.com/webhooks/api/v1/subscriptions/{workspace_id}/{subscription_id} | jq .

Notes:

  • the {secret} field may not be empty,
  • the {subscription_id} field is the ID of the existing subscription to update,
  • read the API reference for the subscription update endpoint.

Change enabled flag in a subscription

curl -u {api_token}:api_token \
-X PATCH \
-d '{"enabled": false}' \
-H 'User-Agent: {user_agent}' \
-H 'Content-Type: application/json' \
https://api.track.toggl.com/webhooks/api/v1/subscriptions/{workspace_id}/{subscription_id} | jq .

Notes:

  • the {subscription_id} field is the ID of the existing subscription to patch,
  • read the API reference for the subscription patch endpoint.

Delete a subscription

curl -u {api_token}:api_token \
-X DELETE \
-H 'User-Agent: {user_agent}' \
https://api.track.toggl.com/webhooks/api/v1/subscriptions/{workspace_id}/{subscription_id} | jq .

Notes:

  • the {subscription_id} field is the ID of the existing subscription to delete,
  • read the API reference for the subscription delete endpoint.

Ping a subscription to test the setup

You will receive a dummy event in the registered URL endpoint for {subscription_id}.

curl -u {api_token}:api_token \
-X POST \
-H 'User-Agent: {user_agent}' \
-H 'Content-Type: application/json' \
https://api.track.toggl.com/webhooks/api/v1/ping/{workspace_id}/{subscription_id} | jq .

Notes:

  • this enpodint allows the configured endpoint URL to receive a special dummy event regardless of whether the subscription is enabled or validated at the moment,
  • read the API reference for the subscription ping endpoint.
© 2024 Toggl. All rights reserved.