How to activate the Notification API?
To activate the Notification API go to Settings → Smart Home Connections → Activate Notification API
Please note our security implementation guidelines!
How are the notifications sent?
The structure of the request is determined by ekey
-
Directory path
-
JSON content
-
POST method
Customer/integrator can determine some basics
-
Basic URL (host name, port)
-
MDNS also possible (mdns-name.local)
-
Customer has to implement HTTP/S server
-
Timeout
-
Security
-
Authentication
All notifications triggered by finger will have URL/api/notification/finger and all notifications triggered by input will have URL/api/notification/input in the address.
When are notifications sent?
-
Finger was recognised
-
Rule exists
-
Rule present but filter active (schedule, deactivated user → user without function)
-
No rule available
-
Finger was not recognised
-
However, match quality of the finger image must be given (fingertip, etc. are not notified)
-
Digital input is triggered
Content of Notification Body
| Name | Value | Description/Example | Data type |
|---|---|---|---|
| Time and Date | time | 2024-03-27T10:22:58Z | string |
| Input Typde | type | 10 | Integer |
| Result | result | 10 | Integer |
| Result Detail | detail | 10 | Integer |
| Executing Device | ctlDevId | 4500080101000001 | String |
| Acquiring Device | acqDevId | 4500070101000001 | String |
| User ID | userId | tKlLpvUa | String |
| Finger Index | fingerIndex | 2 | Integer |
| Digital Input | inputNumber | 1 | Integer |
| Input Trigger | trigger | posedge | String |
The time is specified in UTC.
Input Type Values
| Name | Value |
|---|---|
| Finger | 10 |
| Digital Input | 20 |
Result Values
| Name | Value |
|---|---|
| Unknown | 0 |
| Match | 10 |
| Filtered Match* | 20 |
| No Match | 30 |
- schedule, deactivated user;
Result Detail Values
| Name | Value |
|---|---|
| Unknown | 0 |
| Input Disabled | 10 |
| Time Schedule | 20 |
| No Rule Found | 30 |
| No Input Found | 40 |
| Invalid Input | 50 |
| Time Limitation | 60 |
Finger Index
| Name | Value |
|---|---|
| Left Little Finger | -5 |
| Left Ring Finger | -4 |
| Left Middle Finger | -3 |
| Left Index Finger | -2 |
| Left Thumb | -1 |
| None | 0 |
| Right Thumb | 1 |
| Right Index Finger | 2 |
| Right Middle Finger | 3 |
| Right Ring Finger | 4 |
| Right Little Finger | 5 |
If a ‘null’ is returned instead of a value, then no further information is available.
System Export – Mapping
To see the mapping of your notifications request body, you will get a .JSON file to export from the ekey bionyx app. In that file there are your current users and devices with names and IDs listed.
Example Request Bodies
Here we would like to show some examples, how the request bodies will look for certain events.
Positive Match – green
{
"type": 10,
"result": 10,
"detail": null,
"time": "2024-05-29T15:47:42Z",
"ctlDevId": "4500080101000035",
"acqDevId": "4500070101000025",
"params": {
"userId": "tKlLpvUa",
"fingerIndex": 2
}
}
Digital Input
{
"type": 20,
"result": 20,
"detail": 10,
"time": "2024-05-06T09:16:43Z",
"ctlDevId": "4500080101000035",
"acqDevId": "4500080101000035",
"params": {
"inputNumber": 1,
"trigger": "posedge"
}
}
Rejection – Invalid Input – red
{
"type": 10,
"result": 30,
"detail": 50,
"time": "2024-05-29T10:31:14Z",
"ctlDevId": "4500080101000035",
"acqDevId": "4500070101000025",
"params": {
"userId": null,
"fingerIndex": null
}
}
Rejection – Unknown Input – green/red
{
"type": 10,
"result": 30,
"detail": 40,
"time": "2024-05-29T10:15:16Z",
"ctlDevId": "4500080101000035",
"acqDevId": "4500070101000025",
"params": {
"userId": null,
"fingerIndex": null
}
}
Rejection – Schedule – green/red
{
"type": 10,
"result": 20,
"detail": 20,
"time": "2024-05-29T15:47:34Z",
"ctlDevId": "4500080101000035",
"acqDevId": "4500070101000025",
"params": {
"userId": "tKlLpvUa",
"fingerIndex": 2
}
}
Testing
For testing the whole process, you can use the following site in your browser. There you will get a predetermined URL and you just have to copy it into the Notification API URL area.
