What the card swipe webhook is and who calls it
The card swipe webhook is the integration point between your existing access control system and InnerWeb. The access control system sends an HTTP POST request to InnerWeb at every card swipe on a reader. There is no need to install new readers, change the wiring or replace cards: InnerWeb is a software vendor and integrates with the access control system the plant already owns.
The caller is always the access control system, not InnerWeb. The access control vendor or administrator configures the rule that sends the event after a swipe. On the InnerWeb side, the swipe is assigned to a person, checked against training and saved in the account history. In this way the card number from the access control system becomes the key to important OHS trainings, qualifications and permits.
How to authenticate the call and how long the token is valid
The webhook call requires a JWT token. The integrator obtains it from the API login endpoint and then attaches it to every swipe request. The token has a limited validity period and is renewed automatically by the integration. The integrator should describe in the specification how the session is renewed, because the continuity of sending swipes depends on it.
Practical pattern: a technical account used only for the integration, login when the service starts, automatic token renewal with a margin before it expires, and a new login after a response rejecting the authorization. Passwords and tokens should not end up in the service logs on the access control side.
What to do when the token expires during a change
Swipes made while the token was invalid must not be lost. Good practice is a queue on the access control side: a failed call goes to a buffer, the service logs in again and resends the events in order. A queue makes sense only if events are sent almost in real time, as described below.
Fields in the card swipe report
Which fields are required in a swipe report
The report carries the event time, the place of the swipe and the person's data. The first and last name and the company name are required. Optionally, you can pass a short name, the active card number, phone, email and language. The fuller the set, the easier the match to an existing account and the later notifications in the person's language.
The active card number is the identifier through which InnerWeb links the swipe to the person's account. An external company is assigned based on the company name in the report. If the same agency appears in the access control system once with its full name and once with a short name, discrepancies will arise, so the integrator should pass company names in one consistent spelling.
- Required: first and last name of the person and the company name.
- Recommended: active card number as the matching key to the account.
- Optional: short name, phone, email, language.
- Always: event time and place of the swipe.
What happens when the card or the person is unknown
When a person unknown to the system swipes a card, the system creates an account and a company from the data in the report. This is convenient with high turnover of agency workers, but it requires discipline in the data: a typo in a surname or company name will create a duplicate. That is why the question "what about an unknown card" in practice means "who is responsible for the quality of the source data in the access control system".
When the same person has two active accounts, the system moves the training result to the account with the entry card, so that the gate stops reporting a missing training. It never merges accounts based on the surname alone, because that would lead to mistakes between people with the same surname.
Event time, direction and duplicates: specification requirements
The integration specification requires the access control system to send events in real time, with the event time read from the reader, without batches and night-time uploads. This way the swipe times in InnerWeb match the actual passages through the gate, and network delays do not distort the time records.
Each event from the access control system should carry the direction (entry or exit) and an event identifier, and InnerWeb accepts them through an authenticated webhook. The rules for pairing entries and exits and for rejecting duplicates are set in the specification with the access control vendor. At sites with several work agencies the traffic can exceed 2,000 swipes per working day, so the integration must handle bursts of events and retries.
Checklist
Video
Frequently asked questions
Do we need to replace readers to run the integration?
No. InnerWeb does not manufacture or replace access control readers. The integration consists of sending the event from the existing access control system to InnerWeb with an HTTP POST request.
How does token authentication work?
The JWT token from the API login endpoint has a limited validity period. The integration renews it automatically, with a margin before it expires.
Will InnerWeb record the swipe time from the reader?
The integration specification assumes that the access control system sends events in real time, with the event time from the reader.
How does InnerWeb know the direction of entry and exit?
The direction and event identifier are sent by the access control system. The rules for pairing entries and exits and for rejecting duplicates are set in the specification with the access control vendor.
Sources
Let's talk about the integration with your access control system
We will pass the webhook specification to your access control vendor and go through the fields, the token and real-time sending with them. Book a call with the InnerWeb team.
Let's talk