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.

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}' \
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}' \
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}' \
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:

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}' \
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,
  • these dummy events are not available for consumption in the events endpoint,
  • read the API reference for the subscription ping endpoint.

Get information about matching events for a subscription

We store events that we attempted to deliver to a subscription for a week, you can get information about them (creation date, number of failed delivery attempts, last delivery error, ...) by using the special endpoint /subscriptions/{workspace_id}/{subscription_id}/events.

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

Response example:

{
"total": 2,
"events": [
{
"event_id": ...,
"created_at": "2022-05-31T02:56:52.493Z",
"creator_id": ...,
"metadata": {
"path": "/api/v9/workspaces/{workspace_id}/projects",
"model": "project",
"action": "created",
"project_id": ...,
"request_type": "POST",
"workspace_id": "{workspace_id}",
"event_user_id": ...
},
"payload": {
...
},
"consumer_id": ...,
"last_delivery_attempt": "2022-05-31T02:56:54.205984Z",
"last_delivery_error": null,
"failed_delivery_attempts": 3
},
...
]
}

Note: read the API reference for the events endpoint.

© 2022 Toggl. All rights reserved.