---
locale: "en"
updated_at: "2025-10-29T15:12:11.700Z"
canonical: "https://www.isdecisions.com/en/userlock/docs/build-with-userlock/userlock-webhook"
---

# Using webhooks with UserLock

Integrate UserLock events with external tools via WebHooks.

## Overview

UserLock can send **webhook notifications** whenever a session event occurs, such as logon, logoff, lock, unlock, or denied logon.

Each event is sent as a **JSON notification** to a web application of your choice, containing detailed information about the user, machine, IP address, session type, and timestamp.

This makes it easy to:

- Feed detailed logon data into **SIEM** or **monitoring tools**.
- Integrate with **time and attendance systems**.
- Automate responses (e.g., block a user in Active Directory after a suspicious logon).
- Synchronize **UserLock events** with **physical access control** or HR applications.
- Trigger **custom workflows** through **[UserLock API](/userlock/docs/build-with-userlock/userlock-api)**.

## How it works

When a session event occurs, the UserLock Server sends a JSON notification to the configured webhook URL.

If a **Backup Server** is deployed, it continues to send notifications if the **Primary Server** becomes unavailable. In this way, webhook applications experience **no interruption of service**.

Webhook settings are **automatically synchronized** between Primary and Backup servers, meaning they can only be configured at the Primary level.

## Configure

1. Open the **UserLock console**.
2. Go to **Server settings ▸ General **.
3. Scroll to the **Webhook **section.
4. Enter the URL of your web application (for example:
`https://yourapp.azurewebsites.net/Home/Notify`).
5. Click on the save button.

UserLock will now send JSON notifications for each session event (logon, logoff, lock, unlock, denied logon, etc.).

## Example application

A sample .NET application is available for demonstration:
👉 [https://userlockwebhook.azurewebsites.net](https://userlockwebhook.azurewebsites.net)

This demonstration combines UserLock webhook notifications with a **third-party geolocation web service**.
For every logon event, the app determines the **country of origin** of the connecting user.

> **⚠️ Important:**
>
> The displayed data is **public**, so do **not** test this app using your production environment.
> However, the exposed fields are **non-sensitive**:
> *Event Type, Event Time, User Name, Computer Name, Country,* and *a portion of your UserLock ID* — allowing you to identify which notifications originate from your UserLock instance.

## Build your own

This section describes how to build a simple **ASP.NET MVC** web app to receive and display UserLock notifications.

### Prerequisites

- Visual Studio 2017 or later
- Installed workloads:
  - **ASP.NET and web development**
  - **Azure development**
- An **Azure account** (optional, for deployment)

### Step 1 – Create the project

In Visual Studio:

1. In Visual Studio, select **File > New > Project**.
2. Choose **ASP.NET Web Application (.NET Framework)**.
3. Select the **MVC** template and set **No Authentication**.

### Step 2 – Add dependencies

Use **NuGet Package Manager** to:

- Update all existing packages.
- Install `Newtonsoft.Json` (used to deserialize the JSON notifications).

### Step 3 – Create model classes

Add the following two classes in the `Models` folder:

```cs
public class UserLockServer
{
    public string Id { get; set; }
    public string FQDN { get; set; }
    public string DisplayName { get; set; }
}

public class UserLockNotification
{
    public UserLockServer Userlock { get; set; }
    public int EventType { get; set; }
    public DateTime EventTime { get; set; }
    public string UserAccount { get; set; }
    public string UserDomain { get; set; }
    public string UserFullName { get; set; }
    public string ComputerName { get; set; }
    public int ComputerSession { get; set; }
    public string ClientName { get; set; }
    public string ClientAddress { get; set; }
    public string SessionId { get; set; }
    public int SubSessionId { get; set; }
    public int LogonInfo { get; set; }
    public int SessionType { get; set; }
    public string ServerAddress { get; set; }
    public int TimeZoneShift { get; set; }
    public string Param1 { get; set; }
    public string Param2 { get; set; }
    public string Param3 { get; set; }
    public string Param4 { get; set; }
    public string Param5 { get; set; }
    public string Param6 { get; set; }
}
```

### Step 4 – Implement the controller

The controller receives notifications, deserializes them, and displays them in real time.
You can use the example provided in the [Microsoft Azure documentation](https://learn.microsoft.com/azure/app-service/).
The sample code uses an `Index` page that automatically refreshes and a `Notify` method to handle incoming POST requests.

### Step 5 – Add security verification

To ensure notifications come from a **trusted source**, define a whitelist of **UserLock IDs** in your `web.config`:

```xml
<appSettings>
  <add key="UserlockIds" value="{primary_GUID};{backup_GUID};" />
</appSettings>
```

Then, in your controller’s `Notify` method, enable the check:

```cs
if (!_userLockIds.Contains(ul.Userlock.Id))
    return new HttpStatusCodeResult(HttpStatusCode.OK);
```

This ensures that only notifications from declared UserLock servers are processed.

### Step 6 – Build and publish

1. Build the project.
2. Right-click the solution → **Publish** → select **Microsoft Azure App Service**.
3. Deploy using your Azure subscription.
4. Verify that notifications appear in your app.

## Security

### Validate trusted sources

Each JSON payload includes a field called **UserLock ID**, unique to your UserLock server.
Your webhook should always verify this value to confirm the sender’s identity.

### Retrieve or reset the UserLock ID

On the UserLock server, open **PowerShell** and run:

- Retrieve:
  ```powershell
  Get-UserLockServerConfiguration -Property 'ServerGuid'
  ```
- Reset (only if compromised):
  ```powershell
  (Get-UserLockServerConfiguration).ResetGUID()
  ```

> **⚠️ Important**
>
> Resetting the ID should be rare.
> If you do, update all webhook applications to trust the new value.

## Use cases

Webhooks extend UserLock’s automation and monitoring capabilities:

- Send session events to a **SIEM** (e.g., Splunk, Sentinel, QRadar).
- Automate responses using **PowerShell or the UserLock API**.
- Log employee hours in **HR systems**.
- Sync digital and **physical access control**.
- Detect and act on **anomalous login behavior** in real time.

## Limitations

Only records from the "UserLogonEvents" table are passed to the webhook. Records from the "UserStatus", "AdminActions" and "AdminActionResults" tables are not passed to the webhook.