Plans 💳 : Everyone

User Permissions 👥: Admins
For legacy plans, please refer to the article here.

Complimenting Timely’s already available API, we’re now proud to offer enhanced capabilities in the form of Webhooks!

Webhooks help you to programmatically connect Timely to other apps without the need for repeated API calls. Timely can “push” out data and updates for a specific endpoint whenever changes are made. The Webhook makes sure that a HTTP request is sent to a URL of your choosing.

For those newer to development work, you can think of a webhook as being similar to a notification, with Timely sending out an update to your app to “notify” it of certain changes.

Webhooks can be set up within Timely directly, via the Webhooks section of the Settings area, or via the API. You’ll find additional information in the “Webhooks” section of the Timely API Documentation.

Configuring a Webhook within Timely:

Go to Settings > Webhooks and click on “New Webhook” button to create a Webhook.

When setting up a new webhook you have to specify the URL where the HTTP request is sent to as soon as any of the trigger events takes place. You are able to specify multiple URLs in this section as needed.

Setting a “secret token” is optional and allows you to verify that the sent request comes from Timely. You’ll find additional context in Timely’s API documentation that provides further information on how to verify received calls.

You can subscribe to certain events by clicking on them. Using the [control] or [shift] keys on your keyboard, you are able to select multiple events as needed.

Available Webhook events:

  • forecasts:created

  • forecasts:updated

  • forecasts:deleted

  • hours:created

  • hours:updated

  • hours:deleted

  • labels:created

  • labels:updated

  • labels:deleted

  • projects:created

  • projects:updated

  • projects:deleted

After you’ve successfully created a Webhook in Timely, you’ll see it listed in the Webhooks section moving forward. You’ll see the target URL, specific trigger events,the secret token, and the status.

By clicking the “Delivery Logs” button you can see the recent deliveries listed.

What do Webhooks look like on the receiving end?

The Webhook is a HTTP POST request and the body of the request contains all the relevant information. See below the body of a request which was triggered by a created project.

FAQs

How do I test my Webhook?

Just use your favorite search engine and use the search term “test webhook”. (As you can see from the screenshots shown here: https://webhook.site/.) You’ll find websites that provide an URL where you can send the Timely Webhooks to test them. In order to check if everything works as expected on the Timely side, you can always have a look at the delivery logs as described above.

How can I delete my Webhook?

We recommend deactivating Webhooks instead of deleting them. This can be done by editing the Webhook and removing the check next to “Active”. If you are certain this Webhook will never be used again, you can use the “Destroy” button to permanently remove it. Both functions are also available via the API.

What is a common use case for Webhooks?

Webhooks are used to make sure that new or updated data is synced from one app to another in close to real time.

For example, you may have two separate apps as well as a service that moves data in and out of each. A Webhook can be used to alert the service that data has been added or changed in one of the apps. Afterwards the service can request the new/changed data and add/update it in the second app.


Did this answer your question?