Webhooks

Overview #

This guide shows how to setup and use the Webhooks.

Use Case #

Here are a few examples, how webhook can lead to a deeper integration with other systems:

3rd Party Software Integration #

If a 3rd party software needs to be aware of users that login or logout, all ticket.* events can be sent to that endpoint and providing real-time data to the software. This also allows you to react on used-up tickets.

Batch Access API #

The Batch Access API is a perfect companion, as it allows you to create tickets or autologin devices. The webhook events will inform your service about expired tickets.

Monitoring #

The system.* events can be used to trigger alerts or notifications if the system is rebooting, creates backups, etc..

System settings #

• Under APIs -> Webhooks enable the webhooks feature.
• Under the first tab, Webhooks new endpoints may be defined. See Webhook settings for details.
• The second tab shows processed events including the returned response.
• General settings, which apply to all webhooks can be found in the third tab.

Webhook settings #

To setup a webhook fill out the required fields on the configuration page. The following table shows all available settings:

Authentication #

Authentication settings depend on the setup of your desired webhook endpoint. The webhook endpoint supports no authentication (not recommended), HTTP basic auth and bearer token authentication.

Events #

Currently the following events can be set to send a message:

• Ticket
  • login
  • logout
  • logout due to timeout
  • logout due to exceeded limit
  • revoked
• System
  • (re)start
  • userlimit exceeded
  • backup
    • started
    • done
    • error
• More to come (talk to us, if you need specific events)

Note that the same endpoint can be used with different settings (e.g. headers or body) for different events by saving it as copy and changing the relevant fields.

Event data fields #

The event.data json contains the following fields. All fields are sent, but only filled if data for them is available. All fields are also available as placeholder with the same field name.

For PMS tickets, more data about the the ticket is contained in backend_data. These fields can also be accessed via placeholder directly by using dot notation and are only filled depending on the type of ticket and PMS used. (e.g. backend_data.pms.room, backend_data.pms.name, backend_data.pms.departure )

An example configuration is shown here:

{
	"id":"{{event.uuid}}", 
	"event":"{{event.type}}",
	"occured":"{{event.created_at}}",
	"ticket_id":"{{event.ticket_id}}", 
	"volume_limit":"{{volume_limit}}",
	"volume_used":"{{volume_used}}",
	"volume_limit":"{{volume_limit}}",
	"room_number":"{{backend_data.pms.room}}"
}

Event missing? #

Please reach out to us via support@iacbox.com.

Event log #

All processed events which are stored in the database are shown here to simplyfy debugging. More details can be displayed if the option to log body and headers is activated. Events will only be sent once to each endpoint, but errors (e.g. no response) will be logged here.

General settings #

Cleanup event log #

In order to avoid overfilling the database with old events, they are periodically removed. The interval can be set here. Logging for longer than one week is not recommended, for large system even lower intervalls may be sensible.

Read interval #

Set the time interval in seconds in which the event queue will be processed. Defaults to 10 seconds.