Follow

Webhooks: Getting Started

What are webhooks?

  • Webhooks are push notifications triggered by events in LiquidPlanner.
  • An event is the creation or update of a record such as a comment or task.
  • The notification consists of JSON that is POSTed over HTTPS to a target URL that you specify.

Why would I use webhooks?

You can use webhooks to integrate LiquidPlanner with external systems. 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.

Who can configure webhooks?

Only a workspace owner or administrator can configure webhooks.

How do I get started?

  1. As the workspace owner, go to the User Menu > Settings.
  2. In the Extras section, click on Webhooks.
  3. Click the Create New Webhook button.
  4. Enter the target URL (see "What's a target URL?" for more info).
  5. Leave the Event field set to "* (all updates)" to be notified about everything. Or, select the specific type of record that you want notifications for.
  6. Click the enabled checkbox.
  7. Click save.

When will my webhook be triggered?

  • Webhooks are triggered by the creation or update of a record.
  • Depending on your selection in step 5 above, you'll either trigger for all records (i.e. projects, tasks, comments, ...), or only a specific kind of record (e.g. comment).

What 's a target URL?

It could be a script you write or a third-party service. The requirements are:

  1. Accessible from the Internet using HTTPS.  We require the target URL to be HTTPS (not HTTP) for the same reason it's required for the LP application -- it keeps your information secure in transit.
  2. Accepts POST requests with JSON bodies

You can use RequestBin (https://requestbin.herokuapp.com) to get started -- it simply dumps request contents, useful for testing or debugging.

What does a notification look like?

The 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'; use e.g. only take action on newly created records, and not updated ones
  • changes - only for updates, a hash containing the previous values of changed attributes; use e.g. to only take action if owner_id or is_done is updated

For example, changing the name of a project will produce a notification like:

{ "alerts": [], "change_type": "update", "changes": { "name": "Project Foo" }, "name": "Project Bar", "type": "Project", "work": 0.0 }

where most of the project attributes have been omitted for readability.

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? How do I 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.

 

Click here for a blog post on Webhooks.

Got questions about Webhooks?  Please search for answers and/or post in our Developer Community. Thanks!  

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request