InnerWeb
Skip to main content

KD with OSDP and the event webhook: implementation notes for the administrator

After replacing Wiegand readers with OSDP, the KD administrator fears that integrations with external systems will stop working. The rule is simple: InnerWeb receives events from the KD system, not from the reader, so changing the reader-to-controller link does not change the webhook contract. Below is a list of things to check at the switchover.

443
port of the outbound integration connection
Source: internal integration card
12 h
validity of the JWT token
Source: internal integration card
2,100
punches a day in a similar integration
Source: internal deployment card

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

KD integration parameters with InnerWebHorizontal bar chart: 2,100 punches a day, pairing window 780 minutes, token 12 hours, duplicate threshold 180 seconds.05001000150020002500valuePunches a dayPunches a day: 2100 value2100Pairing window (min)Pairing window (min): 780 value780JWT token (h)JWT token (h): 12 value12Duplicate threshold (s)Duplicate threshold (s): 180 value180
Source: Internal KD integration card; the 13-hour window converted to 780 minutes

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