Webhooks - Anatomy of a webhook plugin

If you haven't already, I would encourage you to read the Webhooks Introduction page so that you have an idea of what a Jomres Webhook plugin does. If you are interested in creating Jomres plugins in general, then a good place to start is the Hello World plugin example.

This page does not teach you to code. Instead it is designed to give you the basics of a Webhook plugin's structure so that experienced developers can quickly create their own plugins for sending information from Jomres installations to remote services when certain activities are performed.

As a result I will skip looking at the code itself. If you want to make your own webhook plugin I recommend that you install the "Webhooks Authmethod None" plugin in the Jomres Plugin Manager, then you can compare this guide to the files, and potentially use that plugin as a foundation for building your own code. It's released under the GPL so you are free to copy and adjust those files as needed.

Like almost all Jomres plugins, functionality is provided through Minicomponents. For a summary of the Minicomponent trigger numbers, see this page on Github.

webhook plugin files

 

There are 4 files in this plugin. You could of course your own class files if needed, but they might not be required.

 
plugin_info.php

All Jomres should have a plugin info script. See the Hello World example mentioned above for more information on them.

j00005webhooks_authmethod_none.class.php

This script is run whenever Jomres is run and it is used to include the language file in the /language/ sub-directory.

j07300webhooks_auth_method_none.class.php

This script is used to tell the webhook page that a certain webhook exists, and what language strings and settings it uses. This information is used both on the New Webhook page and when you change the Authentication Integration dropdown on that page.

j07310watcher_authmethod_process_none.class.php OR j07320watcher_authmethod_process_none.class.php

When an action is performed in Jomres, and Jomres finds that there is a Webhook or Webhooks for that property's property manager, then the webhook handling is triggered, and the appropriate script is called to process the action.

This script is given the action's information and it's this script's responsibility to authenticate with the remote site, using the previously stored login information, and to send the body of the action that was performed.

07310 scripts are processed immediately, whereas 07320 are treated as deferred tasks (more information below). Where possible I would strongly recommend that you use 07320 scripts. Debugging them is trickier but there is a shortcut (again, described below). This is because remote communications to other services might not be instantaneous and processing 07310 scripts could create a bottleneck whereas 07320 scripts do not.

 

Communication summary

Because a webhook's call to a remote service can be very time consuming, Jomres doesn't process webhook calls during it's normal run. This allows the user to continue using the software after performing an action that triggers a webhook or webhooks without needing to wait for the webhook to complete.

Instead the webhook watcher script j99994webhook_watcher.class.php finds any webhooks that need to be triggered for that property manager, then creates as many deferred tasks as needed. These tasks are then packaged up by the jomres_deferred_tasks class which writes a temporary file with the webhook's details to the temp data directory. Once that's done, then Jomres calls itself to tell itself that this new background task exists. The same jomres_deferred_tasks class will read in that file when Jomres receives the notifcation (j06000background_process.class.php) and trigger the 07320 that actually performs whatever the webhook is supposed to do.

Whilst this may seem a convoluted process, the reasoning for doing it is sensible. For example, when a tariff is updated in Jomres, a webhook is triggered to send the new pricing information to Beds24, if connected. Collecting and sending this information to Beds24 can take time and there's always a danger that the user could get frustrated while waiting for this to finish. When we use the background tasks method of calling ourselves then user activities continue as normal and the webhook tasks happen in an independent process that the user can't accidentally or deliberately prevent from completing.

This also means that arguably the webhook activities lag behind what the user has been doing, although typically only by a few seconds or so.

If you want to know if a webhook has been completed, check the Administrator > Jomres > Tools > Available logs > Webhooks.application.log. This should show you if and when the 07320 event was fired and any logging that you might create by adding the following to a webhook script :

logging::log_message("Blah blah was done" , 'Webhooks', 'DEBUG'  );

Debugging 07320 scripts

As a developer, you may find yourself needing to debug a webhook's 07320 script. Rather than having to constantly trigger a webhook by doing something, potentially time consuming in Jomres, there is a shortcut.

Assuming that you have created a webhook plugin and have created the webhook in the Jomres frontend property manager's UI, you now want to test and or debug that the notification is going to the remote service.

First put the site into Development mode (Administrator > Jomres > Settings > Site Configuration > Debugging tab). Once you have done that the temporary files that are created and then deleted by the j06000background_process.class.php and jomres_deferrered_tasks scripts are not deleted after the webhook has been processed.

Next, perform the task that should trigger a webhook, for example create a booking, save a tariff etc.

Go to the Administrator > Jomres > Tools > Available logs > Core.application.log and in the search field you can enter something like this :

search logs for background

When you do that you'll see a list of calls to the background_process script. An example might look something like

http://localhost:80/joomla_portal/index.php?option=com_jomres&no_html=1&jrajax=1&Itemid=103&lang=en&task=background_process&payload_source=GiJxalSBOqqkAlPGiUIgvhJQhgWnonOoSkxzNOtCUvVLOzkWBa

You can now copy that url into your browser's address bar to trigger the actual 07320 script without needing to laboriously create bookings, change tariffs etc.

If you want to see what was passed to the webhook 07320 script then look in /jomres/temp/deferred_tasks for a file with the name of the payload source, eg GiJxalSBOqqkAlPGiUIgvhJQhgWnonOoSkxzNOtCUvVLOzkWBa  You can open that file in a text editor to see it's contents.