Web Events

This feature was first released as part of Nimblex 5.6.

A Web Event is a trigger point that you can set up on your Nimblex system, to trigger a form Custom Event when a HTTP Request is made from another system.

Using this technique we can listen for activities that occur in another system (via a web hook), and drive action in your Nimblex system.

You will find them in the Control Panel here:

Click on the highlighted ‘Web Events’ link and you will see a list of all the existing Web Events:

Click ‘Add new record’ to add an event:

Above is all the properties you can set on a Web Event.

Driving Action

When triggered, a Web Event will create a record of the provided EForm and then run the event name provided in the Event name setting. When using an Authentication Key, this event will be executed as the external user account, which will by default have very limited access.

Authentication

You may either require that a username and password is sent via HTTP Basic Authentication, or you may use an ‘Authentication Key’ that forms part of the URL.

When using an Authentication Key, it is important that your URL remains a secret so that outsides cannot invoke it with whatever level of access you grant it. When using this setting, the event will always run as the external user account. You can grant more access via credentials on Custom Events or on certain Task types, but do so with great care.

Processing Data

You may optionally pre-process the HTTP request data using the ‘Pre-processing’ Formula. If you do not, the request will be passed through the the invoked Custom Event as $eventargs.

If you do pre-process, the result of this formula will take its place as $eventargs.

The Request Object

The $eventargs object is of this structure:

HASH(
	"headers", HASH("name1", "value2", "name2", "value2"),
	"query", HASH("name1", "value1", "name2", "value2"),
	"body", "RAW HTTP BODY"
)

Often you will expect your body data to be JSON or XML, in which case the following examples will assist:

JSON

// assume the body is: { "name": "value" }

LET $data := JSONDECODE(HASH_GET($eventargs, "body"));

RETURN TRAVERSE($data, "name")

//Result: String(5) 'value'

XML

// assume the body is: <ol><li>Cheese</li><li>Ham</li></ol>

LET $data := XMLPARSE(HASH_GET($eventargs, "body"));

RETURN TRAVERSE($data, "li", 2)

//Result: String(6) 'Ham'

Debugging

We strongly recommend the free tool https://webhook.site/ for testing.

Related Articles