Device Triggered Webhooks

Device triggered webhooks allow us to inform you of any changes to your device. That means when a particular action is performed, such as the authorisations on your smart lock were changed, or somebody unlocked the door, we can send you an update.

Which actions we inform you of can be changed via the Advanced API settings in Nuki Web, or via the Apikey endpoint.

Type	Description
DEVICE_STATUS	Is triggered when the status of the device has changed.
DEVICE_MASTERDATA	Is triggered when the master data of the device has changed or a sync has been triggered. Includes firmware updates.
DEVICE_CONFIG	Is triggered when the config of the device has changed or a sync has been triggered.
DEVICE_LOGS	Is triggered when an activity log entry is created.
DEVICE_AUTHS	Is triggered when an authorization is created, modified or deleted.
ACCOUNT_USER	Is triggered when an Nuki Web account user is created, modified or deleted.

Note: When testing the various webhook types, you will notice that certain types can duplicate information. This is done to cover as many use cases as possible while keeping the number of options to a practical minimum. If you want to explore all possible options, you can start with all types enabled and reduce them as necessary. All webhook payloads contain the webhook type (labelled feature) which caused them to be trigged.

Examples of each device triggered webhook type can be found below

DEVICE_STATUS

{
    "feature": "DEVICE_STATUS",
    "smartlockId": 123456789,
    "state": {
        "mode": 2,
        "state": 1,
        "trigger": 6,
        "lastAction": 2,
        "batteryCritical": false,
        "batteryCharging": false,
        "batteryCharge": 90,
        "keypadBatteryCritical": false,
        "doorsensorBatteryCritical": false,
        "doorState": 0,
        "ringToOpenTimer": 0,
        "nightMode": false
    },
    "serverState": 0,
    "adminPinState": 0
}

Use cases:

Monitor changes in lock states, such as unlocking and locking
Monitor changes in door states, such as when the door is opened (requires optional door sensor)
Montior battery state via the batteryCritical value
Check if a device is online via the serverState value (data for offline smart locks will be displayed respective of their last state before they went offline)

DEVICE_MASTERDATA

{
    "feature": "DEVICE_MASTERDATA",
    "deleted": false,
    "smartlockId": 123456789,
    "accountId": 987654321,
    "type": 4,
    "authId": 123456,
    "name": "Hello",
    "favorite": false,
    "firmwareVersion": 263940,
    "hardwareVersion": 1792,
    "serverState": 0,
    "adminPinState": 0,
    "creationDate": "2025-03-15T15:54:54.376Z",
    "updateDate": "2025-09-12T12:27:44.819Z"
}

DEVICE_CONFIG

{
    "feature": "DEVICE_CONFIG",
    "smartlockId": 123456789,
    "config": {
        "name": "Hello",
        "latitude": 47.059812,
        "longitude": 15.451866,
        "capabilities": 3,
        "autoUnlatch": true,
        "liftUpHandle": false,
        "pairingEnabled": true,
        "buttonEnabled": true,
        "ledEnabled": true,
        "ledBrightness": 3,
        "timezoneOffset": 0,
        "daylightSavingMode": 0,
        "fobPaired": false,
        "fobAction1": 4,
        "fobAction2": 1,
        "fobAction3": 2,
        "singleLock": false,
        "advertisingMode": 0,
        "keypadPaired": true,
        "keypad2Paired": false,
        "homekitState": 0,
        "matterState": 1,
        "timezoneId": 37,
        "deviceType": 4,
        "wifiEnabled": true
    },
    "advancedConfig": {
        "totalDegrees": 955,
        "singleLockedPositionOffsetDegrees": 0,
        "unlockedToLockedTransitionOffsetDegrees": 0,
        "unlockedPositionOffsetDegrees": 0,
        "lockedPositionOffsetDegrees": 0,
        "detachedCylinder": false,
        "batteryType": 1,
        "autoLock": false,
        "autoLockTimeout": 300,
        "autoUpdateEnabled": true,
        "lngTimeout": 20,
        "singleButtonPressAction": 1,
        "doubleButtonPressAction": 5,
        "automaticBatteryTypeDetection": true,
        "unlatchDuration": 3
    }
}

DEVICE_LOGS

{
    "feature": "DEVICE_LOGS",
    "smartlockLog": {
        "id": "68c4114..........66857b2",
        "smartlockId": 123456789,
        "deviceType": 4,
        "authId": "6788f98..........efb87b3",
        "name": "Nuki Web",
        "action": 2,
        "trigger": 0,
        "state": 0,
        "autoUnlock": false,
        "date": "2025-09-12T12:25:40.000Z",
        "source": 0
    }
}

DEVICE_AUTHS

{
    "feature": "DEVICE_AUTHS",
    "deleted": false,
    "smartlockAuth": {
        "id": "68c1477..........5b70364",
        "smartlockId": 123456,
        "authId": 77,
        "code": 546768,
        "type": 13,
        "name": "Hello",
        "enabled": true,
        "remoteAllowed": true,
        "lockCount": 0,
        "allowedFromDate": "2025-10-15T01:00:00.000Z",
        "allowedUntilDate": "2025-12-22T22:00:00.000Z",
        "allowedWeekDays": 127,
        "allowedFromTime": 0,
        "allowedUntilTime": 0,
        "lastActiveDate": "2025-09-10T09:40:04.000Z",
        "creationDate": "2025-09-10T09:40:04.000Z",
        "updateDate": "2025-09-12T12:37:40.323Z"
    }
}

Use cases:

Monitor newly created or updated authorisations for a device

ACCOUNT_USER

{
    "feature": "ACCOUNT_USER",
    "deleted": false,
    "accountUser": {
        "accountUserId": 123456789,
        "accountId": 987654321,
        "email": "hello@example.com",
        "name": "Max Power",
        "language": "de",
        "creationDate": "2025-09-12T12:00:05.390Z",
        "updateDate": "2025-09-12T12:00:05.390Z"
    }
}