Using Webhooks in 5.10 beta 1

[John Heenan]

Blesta version: 5.10 beta 1
PHP: 8.2.7
OS: Debian 12.5 (stable, bookworm)

My outgoing webhook:

My incoming webhook:

Send the follwing direct to outgoing webhook without Blesta:
 

curl  https://somedomain.com/cgi-bin/dumpalltoemail.cgi -H "Content-Type: application/json" -d {\"testvar\":\"whatever\"}

No problem. I get an email back echoing the json I sent.

Send the same to blesta server, which I would expect to forward on as above:

curl https://someblestaserver.com/plugin/webhooks/trigger/index/testname -H "Content-Type: application/json" -d {\"testvar\":\"whatever\"} 

Nothing echoed back.

Make some changes to any package. Outgoing webhook is not called.
 

 

[John Heenan]

I have just changed the event to Packages.editAfter for both incoming and outgoing webhooks. Still same lack of any effects.

[Paul]

5 hours ago, John Heenan said:

I have just changed the event to Packages.editAfter for both incoming and outgoing webhooks. Still same lack of any effects.

Incoming webhooks require that you have your own plugin that listens for the event so that it can trigger whatever action you want. Outgoing webhooks seem to work for me. Try setting up an Outgoing webhook using https://webhook.site/

This will give you a unique URL to create your webhook using, and the browser page will refresh automatically when the webhook is triggered, showing you the data. I just set up a test using Packages.edit with POST_JSON and the webhook.site page updated with the details.

[John Heenan]

7 hours ago, Paul said:

Incoming webhooks require that you have your own plugin that listens for the event so that it can trigger whatever action you want. Outgoing webhooks seem to work for me.

@Paul, I got the outgoing webhook to work after I removed .cgi at end (and copied script to name without .cgi). But after I put back .cgi again it continued to work. I am not convinced the iniital URL was wrong.

With regard to your statement on incoming webhooks, does this mean there are currently no modules or plugins that listen to any of the events we can set?

1. Can you please give us a very simple example of a module that will listen to some event and will trigger another event harmlessly, such as below.
2. Can you add in extra events, like the following, so we can test without risk of destructive action.

Desired extra events: Test1.beforeTest, Test1.createTest, Test1.deleteTest, Test1.afterTest, Test2.beforeTest, Test2.createTest, Test2.deleteTest, Test2.afterTest

 

[John Heenan]

35 minutes ago, John Heenan said:

With regard to your statement on incoming webhooks, does this mean there are currently no modules or plugins that listen to any of the events we can set?

To make myself clearer, does this mean there are currently no modules or plugins we can trigger a named event through an internal webhook URL? This is apart from whatever extra data may or may not be required or supplied.

Also, does security of internal webhooks rely on an obscure URL path with SSL, or do we need to build in security? Can a header be set to confirm if an admin is making the request?

Also is there a way to determine if an outgoing webhook is not fake, apart from such methods as checking normal web headers that are dispatched with every request?

[John Heenan]

Better still

19 hours ago, John Heenan said:

2. Can you add in extra events, like the following, so we can test without risk of destructive action.

Desired extra events: Test1.beforeTest, Test1.createTest, Test1.deleteTest, Test1.afterTest, Test2.beforeTest, Test2.createTest, Test2.deleteTest, Test2.afterTest

Better still, can you tell us how we can register events of our own choosing for triggering and subscribing to?

I have changed the title of this topic to better reflect the current issue

[John Heenan]

With regard to outgoing callbacks/Webhooks:

On 4/20/2024 at 10:55 AM, John Heenan said:

Also is there a way to determine if an outgoing webhook is not fake, apart from such methods as checking normal web headers that are dispatched with every request?

I will answer this question myself. Yes there is and it is dead easy, provided your web server logs are safe from being pried at and provided SSL is used.

Here is an example for a POST JSON method. For an outgoing callback use an entry similiar to

https://someserver.com/cgi-bin/dumpalltoemail.cgi?server=someotherserver&service=blesta5.10.beta1&event=Packages.editAfter&apiKey=somerandomkey

The receving web server can decode this to

server=someotherserver
service=blesta5.10.beta1
event=Packages.editAfter
apiKey=somerandomkey

The apiKey (or something else) can be used to prevent fake callbacks and can even be interpreted to allow a privilege level.

However URL encoding rules need to be followed and it is necessary to double checked Blesta does not mangle the callback entry. At an rate, the above worked as is (with someserver and someotherserver changed).

In addition, environment variables passed through by the web server can be checked, such as REMOTE_ADDR.

The json from the POST is in the body of the request as a string and there were no problems decoding the body back into json. I proved this by decoding the string and then encoding it again (this time as a 'pretty' string).

With regard to incoming callbacks/Webhooks:

7 hours ago, John Heenan said:

Better still, can you tell us how we can register events of our own choosing for triggering and subscribing to?

Again, I will answer this myself. Blesta has good documentation. The relevant link to start from is at https://docs.blesta.com/display/dev/Events

 

[John Heenan]

My impression from looking at source code and documentation is that the events listed for triggering (incoming) or triggered (outgoing) in the Webhooks plugin are from a central register of events in files in the /installdir/core/Util/Events/Observers/ directory. These events have predefined handlers, either in /installdir/core/Util/Events/Handlers/ or in plugins.

The Webhooks plugin reads the contents of files in /installdir/core/Util/Events/Observers/ directory to determine what these events are and caches its results. It adds itself in as an additional handler for these events (if configured to do so by settings for Webhooks) and then further dispactches them through registered outgoing webhooks we have added in. For registered incoming webhooks we add in, it simply triggers the event and passes on data.

So I guess to properly make use of incoming webhooks we need to write our own plugins and make sure the events they are meant to handle are listed properly in a file in the /installdir/core/Util/Events/Observers/, otherwise Webhooks won't know about our events.

A full simple minimal example would be greatly appreciated.

[John Heenan]

To write new plugins using incoming Webhooks, there is enough to adapt from within existing Blesta source code plugins, without further examples.

We don't need to register or include any file in the /installdir/core/Util/Events/Observers/ directory and we don't need to include any handlers in the /installdir/core/Util/Events/Handlers/ directory. Everything can be kept within the plugins directory.

The domains plugin is the only plugin that I am aware of that triggers events and implements self containment as above.

The orders plugin is an example of a plugin that subscribes to triggered domain events.

The webhooks plugin subscribes to domain events as a proxy for outgoing webhooks.

The webhooks plugin can trigger domain events with an incoming webhook. These will be seen by the orders plugin, although there is little point in this as information does not come from the original intended source.

For incoming webhooks it is better to write a plugin specifically to be triggered by an incoming webhook and is a powerful new feature. For example events can be triggered that a server is running low on disk space, that RAM usage is too high, that another server cannot be pinged. The particular advantage of informing Blesta of such alarms is that they can be centrally logged by Blesta, as well as keep others informed of issues who are on a support desk using Blesta.