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.