InnerWeb
Skip to main content

Webhook from the Access Control System to the Complementary System: Implementation Notes for IT

Card swipe events must reach the complementary system from the access control system, and the route runs through a network usually managed by separate IT and OT teams. Below is a list of points to agree with the access control supplier and the OT network, the order of work, and the pitfalls that most often delay go-live.

2
versions of the REST API (v1 and v2, JWT)
Source: karta

What we send and why

InnerWeb receives card swipe events from the existing access control system by webhook and links them with qualifications, work permits, presence and time recording. The access control system remains the owner of the readers and of the decision to open the passage. InnerWeb is an independent complementary system, so it does not replace access control, time recording, HR or ERP.

The platform provides a REST API in versions 1 and 2 with JWT authorisation, and webhooks to the automation platform, where if-then rules can trigger a webhook after an event. For the access control integration, however, the reverse direction matters more: the access control system sends the event.

Agreements with the access control supplier

The specification for the supplier should be a single document. This is the pattern on which the integration of card swipes from the access control system with time recording was built at a packaging manufacturer, without InnerWeb readers.

  • Event format: card identifier, control point, direction, timestamp with time zone.
  • The way the call is authenticated, for example a token in the header.
  • Behaviour on error: retries, intervals, retry limit.
  • Who maintains the dispatch on the supplier side and how a failure is reported.
  • Whether events from rejected swipes are also sent.

Example time for agreements before go-live (working days)

Example time for agreements before go-live (working days)Horizontal bar chart: 5, 13, 5 and 8 working days for the consecutive stages of agreements051015daysSpecification with the accesscontrol supplierSpecification with the access control supplier: 5 days5OT network exceptionOT network exception: 13 days13Tests on one gateTests on one gate: 5 days5Remaining gatesRemaining gates: 8 days8
Source: Example calculation: illustrative assumptions for one plant

Agreements with the OT network

Production networks often block outgoing traffic from the application host. This variant has a ready solution: when the client's network blocks outgoing traffic from the application host, webhooks are stored durably in a queue and collected by a poller over an inbound channel. Events are not lost, and the OT team does not have to open new outgoing connections.

Agree three things with OT: the network segment from which the access control system sends events, the firewall rules for the recipient address, and a service window for changes. It is also worth settling who approves an exception to the policy, because this is usually the longest stage.

Order of work

A good order limits the risk of stopping traffic: first a test environment with test card swipes, then one gate, then the remaining ones. At each stage check the delay, completeness and the match of the card identifier with the person's account.

When events are resent after a failure, the system should recognise duplicates. Agree with the supplier whether an event has a unique identifier, because without one a retry will record the same entry twice.

Implementation pitfalls

The first is a time zone mismatch: an event in UTC read as local time shifts presence by one or two hours. The second is a missing account for a card: the swipe arrives, but there is no one to link it with. The third is the assumption that an encrypted card solves the permissions: it verifies the identity of the medium, and entry is decided by the permissions on the system side. The fourth is the lack of silence monitoring: an integration with no events for an hour in the middle of the day is a sign of a failure, not of calm.

Video

Frequently asked questions

What if the OT network blocks outgoing traffic?

Webhooks are stored durably in a queue, and a poller collects them over an inbound channel. Events are not lost, and OT does not open new outgoing connections.

Is an API needed beyond the webhook?

Not always. The platform provides REST API v1 and v2 with JWT, which can be added when the access control supplier supports a bidirectional integration.

Who is responsible when dispatch fails?

The parties set this in the specification: the access control supplier is responsible for dispatch and controllers, IT and OT for the network, and InnerWeb for receiving and processing the events.

Sources

Agree the webhook with your supplier

We will prepare the event specification and help agree it with IT and the OT team. Book a conversation with the InnerWeb team.

Let's talk