Who this list is for
This list is for the integrator or administrator of the KD system who builds the sending of swipes to InnerWeb. It assumes the readers stay as they are, and the change concerns only what the KD system sends after each card swipe.
InnerWeb does not produce readers and does not replace them, so the quality of the integration depends entirely on the data in the submission. The recommendations below follow from the requirements of the integration specification under which InnerWeb receives and links KD events.
Recommendation 1: always send the active card number
The active card number is the identifier by which InnerWeb links a swipe to the person's account. Without it, the system has to rely on first and last name, which increases the risk of a mix-up between people with the same details.
Rationale for purchasing and IT: the card number field is the key to checking OHS training before the gate lets the person through. The permit, qualifications and trainings are linked to the person's account, and the card number from KD becomes the key to that account.
Submission fields by category
Recommendation 2: first and last name as a required field
First and last name is required in the submission. A submission without it cannot create an account or assign a swipe to a new person. The vendor should therefore send it in the same form as it appears in the KD personnel register, without abbreviations and without additions such as an agency name.
An acronym field is also recommended if the KD register keeps one. It helps tell apart people with the same details.
Recommendation 3: a company name in one consistent spelling
The company name is required, and an external company is assigned based on the name in the submission. A swipe by a person the system does not know creates an account and a company from the submission data, so two spellings of the same company produce two companies.
Recommendation for the integrator: send the company name from a single KD dictionary field, not from a free text field. If there is no such field, agree on one binding spelling with the KD administrator.
Recommendation 4: swipe location from a fixed dictionary
The swipe location field tells the readers apart. Events from a location that has no template in InnerWeb go to the log and do not trigger the training alert. The integrator should therefore pass the full list of location names from KD, and the OHS team will assign templates to them.
A location name has to be stable. Renaming a reader in KD without informing InnerWeb sends events back to a location without a template.
Recommendation 5: event time and real-time sending
The integration specification requires the KD system to send events in real time, with the event time read from the reader and not the moment of sending. This way the record of entries matches what actually happened at the gate.
The queue of events after a line outage should be emptied as quickly as possible, keeping the original event times, and the integrator should document what delay is acceptable in its system.
When choosing fields, it is also worth listing which of them the KD register fills in automatically and which need manual input by the administrator. Such a list shortens the talk with the vendor and quickly reveals fields that the KD system does not keep at all.
Recommendation 6: phone, email and language only when they are certain
Phone, email and language are additional fields in the submission. Send them only when the KD register contains them and they are up to date, because wrong contact details entered on a new account are hard to catch later. The language field is especially worth filling in for foreign workers, because it affects the version of the training.
Recommendation 7: authentication and handling token expiry
Calling the webhook requires a token from the API login endpoint. The token has a limited validity period and is renewed automatically by the integration. The integrator should repeat the login and resend rejected submissions, not drop them.
A submission should contain the direction (entry or exit) and the event identifier. The rules for pairing entries and exits and for rejecting duplicates are set in the specification with the KD vendor, which is why sending duplicates is not advisable.
Video
Frequently asked questions
Which fields are required in a swipe submission?
First and last name and company name. The other fields, including the active card number, improve how well the swipe is linked to the account.
Does InnerWeb use the reader time?
Yes. The specification assumes the reader event time and real-time sending, together with the direction and the event identifier.
What happens if the company name is spelled differently?
The system creates separate companies for each spelling. It is best to take the name from one dictionary in KD.
Are you a KD integrator?
Get in touch and we will provide the card swipe webhook specification and agree the scope of fields for your system.
Let's talk