Webhooks are push notifications triggered by events in LiquidPlanner. Those events include the creation or update of a record. For example, an event might be the creation of a new project, updates to existing tasks, comments on those tasks, a new time entry, and more. The notification consists of JSON code that is posted to a target URL that you specify. And then you can take that information and do whatever you want with it.
You can use webhooks to integrate LiquidPlanner with external systems, in addition to our API. Since the hooks are event driven and push-based, you don’t need to poll LiquidPlanner, asking “Has anything happened?” As soon as something happens, we’ll let you know.
When setting up a webhook, you can pick the specific type of record that you want notifications about (such as projects, tasks, comments, timesheet entries, etc.) or choose to be notified about everything.
Configuring Webhooks
Only a workspace owner or administrator can configure webhooks by following these steps:
- Go to the User Menu > Webhook Settings > Webhooks.
- Click the Create New Webhook button.
- Enter the Webhook Target URL. The Target URL must be accessible from the Internet using HTTPS (to keep your information secure in transit) and accept POST requests with JSON bodies.
- Select the specific type of record that you want notifications for or leave the Event field set to “* (all updates)” to be notified about everything.
- Click the Enabled checkbox.
- Click Save.
What does a notification look like?
The webhook notification consists of a JSON hash containing the new attribute values for the record. This is like the response you would get from a RESTful GET request to the LiquidPlanner API.
Additionally, there are special keys in the hash:
- change_type – value of ‘create’ or ‘update’. This allows you to, for example, only take action on newly created records, and not updated ones
- changes – only for updates, a hash containing the previous values of changed attributes. For example, you can use it to only take action if owner_id or is_done is updated.
Here is an example of notification you will receive for changing the name of a project (some the project attributes have been omitted for readability):
{ "alerts": [], "change_type": "update", "changes": { "name": "Project Old" },
"name": "Project New", "type": "Project", "work": 0.0 }
What happens if my target URL is down or broken?
If we can’t reach your target URL, we’ll try again in a little while. If we can’t reach the target several times in a row, then we’ll disable the webhook and send you an email.
How can I tell if it’s working, or troubleshoot if it’s broken?
The most recently invoked webhooks for your workspace are displayed in the Webhook Activity Log on your Webhook Settings screen. If we’re having trouble sending notifications to you, we’ll show an error message there.
Related Articles