Where OSDP ends and the webhook begins
OSDP concerns the link between the reader and the controller. The webhook concerns the path from the KD system to InnerWeb. These are two independent layers: after replacing the readers the controller still registers the card punch, and the KD software can still send the HTTPS message.
InnerWeb works as an independent system complementing the client's existing systems (KD, time attendance, HR, ERP), so changing the reader-to-controller protocol does not require changes on the InnerWeb side, as long as the KD system keeps sending events. There is one condition, and it is where reviews after a migration end.
What the message contains and what may change after replacement
A punch message contains the punch time from the controller, the reader identifier, the person, the card number in the form facility_code-card_number, and optionally the direction and the event identifier for idempotency. After a reader replacement the reader identifier may change, if the new reader received a different address or name in the KD system.
Therefore, before the switchover, agree whether the reader identifiers stay the same, or whether the reader-to-location map on the InnerWeb side needs updating. Without this, punches still arrive, but they are assigned to the wrong place.
Direction of entry and exit
If the new OSDP readers allow separate entry and exit, the KD system may start sending the direction field. When there is no direction, the pairing of entry with exit takes place in the InnerWeb software: a window of up to 13 hours and a duplicate threshold of under 180 seconds. It is worth testing both variants before changing the settings.
KD integration parameters with InnerWeb
Network and authentication unchanged
In the integration with the KD system the connection is initiated by the plant as outbound traffic on port 443, so there is no need to open inbound ports in the plant network. Replacing the readers does not change this rule and does not require changes to the firewall rules.
Authentication of the integration uses a technical account and a JWT token valid for 12 hours. At the switchover, check that the KD server renews the token in time, because a long service window may exceed the token's validity and halt the sending of events.
Acceptance test after switching over a gate
After each gate, run the test: a test card punch on the new reader, a check of the event in KD, a check that the event reached InnerWeb, and a check of the reader location. Record the time of the test and the result in the acceptance protocol.
KD events go to the attendance record and, if the module is enabled, to the working time record. The working time module is delivered disabled by default and is enabled by an administrator setting, so the absence of punches does not always mean an integration error.
- test punch and confirmation of the event in KD
- event visible in InnerWeb with the correct reader
- reader location consistent with the map
- no duplicates after a punch repeated in a short time
- result recorded in the acceptance protocol
Idempotency and events after an interruption
If the KD event queue collected punches during the switchover, after sending resumes the events may arrive delayed or repeated. The event identifier provides idempotency: the same event sent twice does not create two punches.
Scale matters at high traffic: in a similar integration running since 2024, about 2,100 punches a day are processed on working days. At such a volume, a service window in the middle of a shift generates hundreds of backlogged events, so it is worth planning it for a production break.
Video
Frequently asked questions
Does replacing the readers with OSDP require changes in InnerWeb?
No, as long as the KD system keeps sending punch events. It is worth verifying the reader identifiers and the location map.
Do inbound ports have to be opened after replacing the readers?
No. The connection is initiated by the plant as outbound traffic on port 443.
What about punches collected during a break?
After resuming they may arrive with a delay. The event identifier ensures the same event is not recorded twice.
Sources
Replacing readers in your KD system?
Describe your KD system and replacement plan. We will help prepare an event test so that punches do not disappear from InnerWeb after the switchover.
Let's talk