Step 1: describe the goal and the scope of responsibility
Start the specification with one sentence of purpose: the access control system sends an HTTP POST request to InnerWeb at every card swipe, and InnerWeb uses it to check trainings, permits and time records. State the boundary clearly: InnerWeb does not supply its own readers for this integration and does not replace readers, so all the work of the access control vendor is configuring the event sending. The detailed integration specification exists as a PDF document handed to the external vendor; this guide describes how to put it in order.
Step 2: authentication and session
The call requires a token obtained from the API login endpoint. The token has a limited validity period and is renewed automatically by the integration, so the specification must require the vendor to renew the token with a margin and to log in again after an authorization rejection. Also record the requirement for a technical account used only for the integration, and a ban on saving passwords and tokens in the logs.
Numbers from the specification
Step 3: fields of the report
List the fields one below another, marking which are required. The report covers the event time, the place of the swipe and the person's data: first and last name (required), short name, company (name required), active card number, phone, email and language. The active card number is the identifier linking the swipe to the person's account, and the external company is assigned by its name. Therefore require one consistent spelling of company names.
- Required: first and last name, company name.
- Matching key: active card number.
- Place: the actionPlace field distinguishing reader locations.
- Optional: short name, phone, email, language.
Step 4: requirements for the event and the sending
Two requirements must go into the specification unambiguously. First, the access control system sends events in real time, with the event time read from the reader, and after a line failure the events keep their original time. Second, each event carries 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 and described as the agreed scope of work.
Add the requirement for resilience to bursts and retries: at a plant with several work agencies, traffic can exceed 2,000 swipes per working day.
Step 5: swipe places and templates
Ask the vendor for a list of readers with the names of the swipe places, in the form they will take in the actionPlace field. Events from a place without a template in InnerWeb go to the log and do not trigger a training alert, so the reader list must be agreed with the configuration on the InnerWeb side before the tests start. A skipped reader is the most common reason for swipes visible in the log but without any effect at the gate.
Step 6: acceptance tests
Describe test scenarios instead of a general statement about testing. Minimum: swipe of a known person, swipe of an unknown person, a repeated swipe within a short interval, a swipe at every reader on the list, token expiry during sending, and a burst of events. The closing criterion: each scenario has an expected result on the InnerWeb side. Remember that the webhook alone without mapping to entries does not produce a time record, so include a test confirming that the swipe is visible in the entry register.
Checklist
Video
Frequently asked questions
Does the access control vendor have to replace readers?
No. The integration is a configuration of the swipe event sending, and InnerWeb does not supply or replace readers.
Why does the specification require real-time sending?
The event time from the reader must be preserved, and delayed sending makes it harder to pair entries and exits and to control attendance.
Who defines the direction of entry and exit?
The access control system passes the direction in every event, and the rules for pairing entries and exits are set in the specification with the access control vendor.
Sources
We will pass the specification to your access control vendor
We have a ready integration document for access control vendors. Book a call with the InnerWeb team and close the deployment in a single iteration.
Let's talk