InnerWeb
Skip to main content

KD reader webhook and outbox queue: recommendations for the IT architect

A card tap event is only useful if it reaches the place where it is used, and an industrial network is sometimes interrupted. The recommendations below show the IT architect how to design the receipt of access control events through a webhook, and how to use an outbox queue so that no event is lost when the receiver is briefly unavailable.

62
events an hour with 1,500 taps a day
Source: sample calculation
125
events to recover after a 2-hour outage
Source: sample calculation

Who this is for and what problem we solve

The recommendations are for the IT architect or integrator who connects the plant's existing access control system with InnerWeb software. InnerWeb is a software producer and does not make or replace readers: it receives card tap events from the KD system through a webhook, while readers, controllers and cards remain on the plant side and with its KD supplier.

The problem is practical. A chemical plant has a network divided into segments, the KD system runs in one of them, the applications run in another, and a firewall stands between them. The link is sometimes unavailable during updates, overload or network works. Every event lost in that time is a potential gap in attendance or working time records.

Recommendation 1: choose the direction: the KD system sends events

Card tap events flow from the KD system to InnerWeb through a webhook, which is an HTTP call with the event data. Design it so that the KD supplier has one place to configure the receiver address and one way to authenticate the calls.

It is worth giving the KD supplier the event specification as a short document: the card or person identifier, the reader identifier, direction and event time. The fewer fields, the lower the risk of incompatibility on the supplier side.

Build-up of pending events during a link outage

Build-up of pending events during a link outageLine chart: 0, 62, 125 and 187 pending events after successive hours of outage.050100150200events0 h1 h2 h3 h0 h: 0 events01 h: 62 events622 h: 125 events1253 h: 187 events187
Source: Sample calculation: 1,500 taps a day, even traffic

Recommendation 2: assume the link will be interrupted

Design the receipt as if a network interruption will happen. An outbox-style webhook queue works so that outgoing events to external systems are first stored durably and only then delivered. If the receiving system is briefly unavailable, the event can be retried because it has not been lost.

This applies to outgoing events from InnerWeb, for example alarm notifications. For incoming events from the KD system the question to the supplier is whether their system buffers and retries calls when the receiver does not respond. This is one of the key points in the integration specification.

Delivery is not instant

When working behind network isolation, delivery depends on how often the queue is polled, so users must not be promised that an alarm will arrive within the same second. An acceptable delay needs to be defined and described in the implementation documentation.

Recommendation 3: a network without outbound traffic is not a blocker

When the plant network blocks all outbound traffic from the application host, alarm webhooks are stored durably, and an external poller picks them up over a working inbound channel and passes them on. The alarm is not lost without opening outbound traffic. This matters for OT teams that do not want to open additional firewall rules.

We recommend discussing this variant with the security department already at the design stage, because it changes the division of responsibility: the poller is a component that someone must maintain and monitor.

Recommendation 4: monitor the queue, not just the service

A queue without monitoring is a silent failure. Define indicators: the number of pending events, the age of the oldest event and the number of retries. An event that goes back into the queue many times is a signal that the receiver does not accept the data or that the data has the wrong format.

In the current implementation a failed delivery in queue mode returns to the pending state and is retried, and retry backoff and attempt limits must be assessed during design. That is why an alert on the age of the oldest event is more important than an error counter.

Recommendation 5: link KD events to what they are for

Card reader events can be linked to qualifications, permits, attendance and working time records. Before you design the flow, write down which of these uses are in scope. Attendance requires a different reliability than statistics, and working time records require a different accuracy than an entry list.

A good approach is to start with one use, for example linking a card tap to the list of people present on site, and then extend.

  • Define the scope of events: entries, exits, refusals.
  • Agree with the KD supplier on the format and the authentication of calls.
  • Set the acceptable delivery delay.
  • Build monitoring of the age of the oldest event in the queue.
  • Test a link interruption in a test environment.

Sample calculation: how many events accumulate during an outage

Assuming 1,500 card taps a day in a plant with several gates and three shifts, the average is about 62 events an hour. A link outage lasting 2 hours means about 125 events to recover. This is a sample calculation: in reality traffic clusters at the start and end of shifts, so the queue may collect events faster. It is important to test the outage scenario during peak hours.

Example calculation

KD events during a link outage

Assumptions
ParameterValue
Card taps a day1500 events
Outage duration2 hours
Traffic distributioneven assumption

Result: about 125 events to recover after a 2-hour outage

Note: Sample calculation; actual traffic is uneven and concentrated at shift changes.

Video

Frequently asked questions

Does InnerWeb supply card readers?

No. InnerWeb is a software producer, and the readers and cards remain on the plant side and with the KD system supplier.

Does the outbox queue guarantee immediate delivery?

No. It guarantees that an event is not lost and can be retried. Delivery time depends on polling and the availability of the receiver.

What about a network without outbound traffic?

Webhooks are stored durably, and an external poller picks them up over the inbound channel and passes them on.

What can KD events be used for?

For linking with qualifications, permits, attendance and working time records, depending on the agreed scope.

Design the KD system integration

We will prepare an event specification for your KD supplier and plan resilience to network outages. Book a conversation with the InnerWeb team.

Let's talk