Webhooks Introduction

A webhook in web development is a method of augmenting or altering the behavior of a web page, or web application, with custom callbacks. These callbacks may be maintained, modified, and managed by third-party users and developers who may not necessarily be affiliated with the originating website or application. The term "webhook" was coined by Jeff Lindsay in 2007 from the computer programming term hook.[1]

Wikipedia

Introduction

 

Jomres offers Webhooks that can inform remote services that certain actions have been performed on a property in a Jomres installation. A full list of the available actions that trigger webhooks can be found on this page.

This feature should be considered as a companion to the API functionality, which receives messages from remote services. Together the two systems can be used to facillitate communications between systems that don't require direct actions by users.

Who can create webhooks?

Only Property Managers can create webhooks. Super Property Managers cannot. This is because Webhooks are associated with Property Manager accounts, not individual properties.

The reason why it's done this way is because webhook notifications are not necessarily done by any specific user, so setting up a tariff might be done by the property manager, whereas making a booking is done by a, potentially anonymous, user. As a result, typically actions are referenced against the property uid and not a property manager.

Webhooks however are linked to managers and not properties because it is the manager who has the relationship with the remote service. This allows a manager to create one webhook for all of their properties, instead of one for each property.

When an action is performed, the manager for the property is determined and any webhook is triggered. Because super property managers do not have a relationship with any specific property it more difficult to find a manager for that property when triggering the hook. In theory it would be possible to search for all super property manager's webhooks, however that would mean sending one webhook action/event to potentially many super managers and there's no telling what chaos could occur if that happened.

What do Webhooks do?

Webhook methods are already built into Jomres, these are simple objects that are created when certain things are done in Jomres. After Jomres has done everything it needs to do, these objects are then handed to the Webhook Watcher class which decides if and what Webhooks need to be triggered.

 

A Webhook performs two main actions when it is triggered. It firstly authenticates itself to a remote service, and it sends the result of the action that was performed on the origin server to the remote service.

These remote services can take many forms. They can be your own server where you have created scripts that perform certain activities when they have been informed of something happening on your site, or they can be services like

Zapier, which offer significant integrations to other tools such as Twitter, Slack, Facebook etc. So you could, for example, update a Slack chatroom when a new booking is added.

 

Different remote services will have different authentication and data requirements, therefore we provide 3 functional Webhook plugins, plus a MailChimp plugin.

  • No Authentication
  • Basic Authentication
  • OAuth Authentication

These plugins will never cover all possible requirements that remote services may demand, however they provide enough functionality to be used as a platform you can build upon in case you need to connect to a service that has it's own set of rules. You could copy or customise one of these existing webhook plugins to suit your own requirements.

 

How do they work?

Webhooks are used to trigger messages to remote systems (e.g. channel managers) when a change is made within Jomres. Because calls to remote systems can take some time, thereby slowing down the user experience, the notification of the change is handed off to the webhook listener (basically is hands a simple object to the listener, such as "room deleted", or similar).

The listener sees this change, takes that object and writes that change to a temporary file. Then the listener calls Jomres again to tell Jomres about this file, then the page finishes running. By calling itself Jomres creates a new thread/process that doesn't impact the original process, this "background" process (it's not really background, but a new process, but you can think of it as a background process) then is free to take as long as it needs to do it's task. Calling remote services can be slow.

Because Jomres calls itself (i.e. the same machine that it's already running on) this call is very very quick and so the original process isn't tied up and can finish cleanly and quickly.