InnerWeb
Skip to main content

FAQ: access control (KD) integration with the OHS and time recording system

Before the start, an access control integrator asks the same questions: in what format to send a tap, how to authenticate, and what happens when the same event arrives twice. Below are the answers that the access control vendor can move into its specification without guessing.

12 hours
validity of the JWT token of the technical account
Source: karta
13 s
refresh interval of the evacuation list
Source: karta
6 groups
division of people on the evacuation list
Source: karta

Who reads the events and who supplies the readers?

InnerWeb is a software producer and does not make or replace access control readers. Readers, controllers and cards stay with the client and its access control vendor. Our system receives card tap events from the existing access control (KD) system through a webhook and links them with qualifications, permits, attendance and time recording.

The access control vendor receives our specification of the tap event. As a result it does not need to learn the internal structure of our system, and the site does not replace its gate equipment.

How does the access control vendor authenticate in the system?

Authentication uses a technical account and a JWT token. The token is valid for 12 hours, so the integration must renew it before it expires, or after receiving a rejection because it has expired.

The technical account is used only to send events. It is not an employee account and should have no rights to view personal data.

  • A separate technical account for each KD system, so that it can be switched off independently.
  • Token renewal with a time margin, not in the last minute of validity.
  • Login data kept by the access control vendor in a secret store, not in code.

Tap integration parameters

Tap integration parametersBar chart: token valid for 12 hours, list refresh every 13 seconds, six groups of people051015numberToken validity (hours): 12 number12 numberToken validity (hours)Evacuation list refresh (s): 13 number13 numberEvacuation list refresh (s)Groups of people on the list: 6 number6 numberGroups of people on the list
Source: Feature cards: KD integration through webhook and evacuation list

What does a tap message consist of?

The message contains the tap time recorded by the controller, the reader identifier, the person and the card number in the form kod_obiektu-numer (site code and number). Optionally, the vendor provides the direction of passage and an event identifier.

The time comes from the controller, not from the moment the message reaches us. This matters for time recording: after a network failure the controller may send delayed taps, and their time is still the true one.

Card number in the form kod_obiektu-numer

The site code tells apart cards from different installations that might have the same number. The system links the card to an employee account, so sending the number without the site code is not enough for an unambiguous match.

Direction of passage

The direction is optional. When you provide it, the system distinguishes entry from exit and calculates attendance. When it is missing, time recording uses the rules set for the given reader.

What does idempotency mean and why is an event identifier needed?

The network is unreliable, so the controller sends an event again when it does not receive a confirmation. Without an event identifier the same tap could be recorded twice and distort the working time.

The event identifier makes it possible to recognise a repeat: a new submission with the same identifier does not create a second tap. For this reason we recommend always providing it, although the field is optional.

What does the system do with a tap on the OHS and time recording side?

Gate scans, which are also used for the evacuation list, form the time recording: daily, monthly and yearly views, exception queues, period closing and reminder calls about an exit that was not scanned. The time recording module is switched off by default, and the site turns it on deliberately.

The evacuation list refreshes every 13 seconds and divides people into six groups: guests, couriers, suppliers, site employees, external companies and uncertain. The data comes from the same taps, so the access control vendor does not send it separately.

How do you test the integration before production start?

We recommend a short test with the gate closed: several taps from the controller, a repeat of the same event, a tap from a cancelled card and a tap after a simulated network failure. The evidence from such a test is a record of events on both sides, which the integrator attaches to the acceptance documentation.

  • Valid tap: one entry is created with the controller time.
  • Repeat with the same identifier: no second entry.
  • Expired token: rejection and successful renewal.
  • Cancelled card: the tap does not grant access that depends on trainings.

Checklist

Video

Frequently asked questions

Does InnerWeb replace readers or controllers?

No. We integrate with the existing KD system and receive events from it. The gate equipment stays with the client and its vendor.

Is the direction field mandatory?

No, it is optional. When you provide it, the system distinguishes entry from exit; without it, time recording relies on the reader rules.

What happens when the same event is sent again?

With the same event identifier, a second tap is not created. Without the identifier the system cannot recognise a repeat, so we recommend always providing it.

Does the time recording module work straight away?

No, it is switched off by default. The site turns it on after agreeing the rules for exceptions and period closing.

We will pass the specification to your KD vendor

Book a call with the integrator: we will go through the event format, authentication and test scenarios before the first tap.

Let's talk