.png)
NoahFace can forward user events to your applications or IT systems. To do this, you simply implement our Event Notification API (a REST Web Hook), and configure NoahFace to call it when a user records an event.
Your implementation of the Event Notification API should expect to receive the following elements:
Your API can be designed to be called using an HTTP GET, PUT, or POST method. If you use GET, the event data will be sent in query parameters. If you specify PUT or POST, the event data will be sent in JSON format (see example below).
The following is an example of the JSON that your API should expect.
{
"eventid" : "109997645",
"utc" : "2018-12-21 21:03:47",
"time" : "2018-12-22 08:03:47",
"org" : "Acme Corporation",
"site" : "Sydney",
"device" : "Time Clock",
"devid" : "",
"type" : "clockin",
"detail" : "",
"method" : "face",
"userid" : "12345",
"number" : "1001",
"firstname" : "Samara",
"lastname" : "Smith",
"usertype" : "Engineer",
"cardnum" : "",
"temperature": 36.9,
"elevated" : false
}Each event includes an event type attribute. The full list of possible event type values is as follows:
Different event types are generated by different screen types. For example, if your are using the Clock In/Out screen, the only event types you will receive are: register, clockin, clockout, startbreak, endbreak, and accessdenied, and if you are using the Task Tracking screen, the only event types you will receive are: register, starttask, clockout, and accessdenied. You can generally ignore register and accessdenied type events.
Each event contains an event detail attribute. This is populated with any data that is collected with the event. For example:
Processing the detail attribute can therefore help you automate cost allocation.
You can forward user events either from the Cloud or locally from the NoahFace App. Forwarding user events from the Cloud is usually used for integration with payroll systems.
To forward user events from the Cloud, simply add a notification, select 'Custom' as the type, and specifying your API endpoint details (see example below). Once you have done this, associate this notification with an access point type, and create your access point.
It is critical that you process Cloud notifications quickly (ie: ideally sub-second, and a maximum of 10 seconds in all circumstances). If you have processing work to do, you must store the notification data, return success, and then perform your processing in the background.
Your API should return an HTTP response code of 200 on success (ie: you have received the data, validated security, and do not need it sent again), and an appropriate response code on failure (eg: 404 if the specified url is incorrect, 403 if access was unauthorised, etc). If you return anything other than 200 (or your API cannot be reached), then NoahFace will attempt to re-send the event the following number of hours in the future:
2 ^ (number of failed attempts - 1)
So, the first retry will be after 1 hour, the second retry will be after an additional 2 hours, the third retry will be after an additional 4 hours, etc. This will continue until your API returns success, or until 90 days has passed.
You can forward user events either from the Cloud or locally from the NoahFace App. Forwarding user events locally from the NoahFace App is usually used for integration with local hardware (eg: unlocking a door or printing labels). You can also use local event forwarding to retrieve and display real time messages to users.
To forward user events locally from the NoahFace App, select your access point type, select 'Web Server' as the Receiver type, and specifying your API endpoint details (see example below). Once you have done this, create your access point.
It is critical that you process local notifications quickly (ie: less than a second) in all circumstances, as local event forwarding is synchronous (ie: users are waiting for the response).
Your API should return an HTTP response code of 200 on success, and an appropriate response code on failure (eg: 404 if the specified url is incorrect, 403 if access was unauthorised, etc). You can optionally return a custom HTTP response header of X-NOAHFACE-MESSAGE to display a message to the user. There is no retry mechanism for local notifications.
Your implementation of the Notification APIs should enforce one of the following authentication methods:
If your implementation of the NoahFace APIs is being designed to service multiple organizations, you should use different credentials for each organization so you can access the appropriate data in your IT system or application.
Regardless of which authentication method you choose, all API calls are over HTTPS so your data and credentials are encrypted (TLS 1.2 and later is supported).
