Webhooks API - Request Examples

Tech Discussions Webhooks API
, , , ,
1

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.