UserLock Documentation
UserLock Documentation
You are here: Reference > Console > Server administration > Webhook notifications

Webhook notifications

UserLock allows you to push updates directly to other applications right when they happen, opening up new automation possibilities. It allows real-time logon notifications to be integrated into other applications or monitoring platforms, and custom workflows can be built based on specific access events.

Every user connection event - and logon attempt – will be notified to the webhook URL alongside all user and machine details associated with the event (IP address, session type, time, etc.)

There are many ways webhooks and the UserLock API can be used to bring UserLock’s data into other apps.

  • Feed granular logon data into your SIEM solution for more accurate analysis.
  • Feed granular logon data into time and attendance systems to accurately log employees hours and overtime.
  • Integrate UserLock with software applications to allow line managers to easily authorize temporary time extensions for any specific user.
  • Trigger real time processes such as blocking a user in Active Directory following a suspicious logon event.
  • Integrate granular logon data with physical access control systems to better control employee’s access to doorways or other entrance portals. (I.e. an attempted access to a building using a compromised badge would be unsuccessful if the user is currently already logged on at their desktop).

To configure the webhook notifications, simply enter your application URL. Once saved, UserLock will automatically send a JSON notification after each session event (such as logon, logoff, lock, unlock, denied logon, etc.).

Note: If the UserLock Primary Server becomes unresponsive the UserLock Backup Server, if deployed, continues to send webhook notifications in addition to handling session events. In this way, webhook applications do not experience any interruption of service. Webhook settings are automatically synchronized between the Primary and Backup servers meaning it's not possible to modify these settings at the Backup server level.

Application example

We provide you a .NET application for demonstration purposes:

This application is combined with a third-party geolocation webservice, which will find, for every logon event sent by UserLock, the country of the user.

The displayed data is public, so we recommend you to not test this with your production environment. Note however the data displayed is not deemed to be of a critical nature (Event Type, Event Time, User name, Computer name, Country and a part of your UserLock ID so that you can easily identify the notifications sent by your UserLock instance).

How to create your own web application

If you want to create your own application, please follow this guide. It will help you to create step by step, the .NET application example shown before (without the geolocation webservice).

Webhooks also allow you to increase the possible integrations of the UserLock API.

How to secure your webhook notifications

Receiving notifications from non-authorized sources can be a problem if a malicious user has decided to dupe your application. To solve that issue, JSON notifications sent by the UserLock service contain a field ‘UserLock ID’ which ensures that all received notifications are from a trusted source.

At this point, please understand that if a ‘UserLock ID’ filter is applied, all notifications sent by a non-authorized server will be dismissed. The field ‘UserLock ID’ is the secret between your application and UserLock. If a member of your organization shares this secret, thus compromising it, you’ll be able to change it (see section Resetting the ‘UserLock ID’ value). However, each time the field ’UserLock ID’ is reset, the white-list of Userlock IDs in webhook applications able to receive JSON notifications must be updated, as the new UserLock ID will once again be an unknown.

Note: if you have deployed a UserLock backup server besides the primary one, please don’t forget to add its own ‘UserLock ID’ to this white-list.

Getting the ‘UserLock ID’ value

To retrieve the field ‘UserLock ID’, please open a Powershell console on the server where UserLock is running and enter the following command:

Get-UserLockServerConfiguration -Property 'ServerGuid'

Resetting the ’UserLock ID’ value

To reset the field ‘UserLock ID’, please open a Powershell console on the server where UserLock is running and enter the following command:


Important! You should only do this operation in rare occurrences. For example when the Userlock ID has been compromised as this would permit untrusted sources to send JSON notifications to your webhook application. Resetting the ‘UserLock ID’ field means all client webhook application(s) need to be updated so that the new secret is accepted (as explained previously).