InnerWeb
Skip to main content

Access control webhook: a guide for the IT administrator

A webhook for access control swipes is an HTTP call by which the access control system passes a card presentation event to another system at the moment it happens. The IT administrator is responsible for making sure the event actually arrives, not merely that it was sent. This guide shows how to define the event, how to check it, and what to do when the plant network blocks outgoing traffic.

89
maximum batch of outbox entries per pickup
Source: documentation of the Webhook Outbox function
300 s
time after which an unconfirmed entry returns to the queue
Source: documentation of the Webhook Outbox function

What a webhook for swipes means

A webhook is an inverted model of integration: instead of querying the access control system every minute for new swipes, the access control system sends the event to the given address itself when a card is presented. The receiver gets the data with minimal delay and does not load the access control system with queries.

InnerWeb receives card swipe events from the access control system through a webhook and connects them with qualifications, permits, attendance and RCP. InnerWeb is a software manufacturer: it does not produce or replace readers and cards, but integrates with the client's existing access control system. The access control side therefore needs a function that sends events, and the InnerWeb side needs an address that receives them.

The event: what it should contain

The IT administrator agrees the specification of the event with the access control supplier. The minimum set is the identifier of the person or card, the timestamp, the identifier of the passage point, and the result of the swipe, that is entry allowed or refused.

If the reader does not report the direction of passage, the swipes are paired on the receiving side: an entry with an exit within a window of up to 13 hours, and duplicates less than 180 seconds apart are discarded. That is why the timestamp must be precise and the time zone unambiguous.

  • Identifier of the person or card, without data that are not needed for the purpose.
  • Timestamp with the time zone.
  • Identifier of the gate or reader.
  • Result: allowed or refused.
  • Unique event identifier, so that a resend does not create a duplicate.

Parameters of event receipt and pairing

Parameters of event receipt and pairingBar chart: duplicate threshold 180 seconds, return of an entry to the queue after 300 seconds, outbox batch of 89 entries, pairing window of 13 hours.0100200300seconds, entries or hours (separate quantities)Duplicate threshold (s): 180 seconds, entries or hours (separate quantities)180Duplicate threshold(s)Entry return to queue (s): 300 seconds, entries or hours (separate quantities)300Entry return to queue(s)Outbox batch (entries): 89 seconds, entries or hours (separate quantities)89Outbox batch(entries)Pairing window (h): 13 seconds, entries or hours (separate quantities)13Pairing window (h)
Source: Cell card and documentation of the Webhook Outbox function

How to check that the event arrives

A response code 200 on the sending side is not enough as proof of effect. Three things must be checked: whether the event appeared in the receiver's system, whether its data are correct, and whether the number of events matches the number of swipes in the access control system.

The platform provides a REST API (versions 1 and 2, JWT) and webhooks to the automation platform. The administrator can therefore compare the number of events on both sides through the API and check the result independently of the sender's report.

Test in three steps

Run the test before going live, and then after every change of network or access control configuration.

  • Present a test card and check whether the event appears in the receiver's system within a few seconds.
  • Present the same card twice within less than 180 seconds and check whether the duplicate was rejected.
  • Cut the connection briefly and check whether the events after its return are not lost.

When the plant network blocks outgoing traffic

In plants with a restrictive network policy the application server is sometimes cut off from outgoing traffic. Outgoing InnerWeb webhooks can then be queued in an outbox table, and an external poller collects the batch over an incoming channel. The mechanism concerns sending from the platform, not receiving swipe events from the access control system, but the same rule has to be settled when the network is designed.

In the documentation of the function, one batch pickup covers up to 89 entries, and a blocked entry returns to the queue after 300 seconds if it has not been confirmed. For the administrator these are the parameters worth knowing when assessing delay in an isolated network.

Audit evidence and maintenance

The evidence is the record of events on both sides with the same identifiers. Once a quarter it is worth comparing a sample, because a silent webhook failure shows up as missing events, not as an error.

Gate scans form the working time record (RCP) with daily, monthly and yearly views, exception queues and period closing. Missing events therefore land in exceptions, but only if someone reviews those queues.

Video

Frequently asked questions

How does a webhook differ from polling an API?

A webhook sends the event at the moment it happens, while polling requires periodic queries. A webhook gives lower delay and does not load the access control system.

How do I check that an event was not lost?

Compare the number and identifiers of events in the access control system and in the receiver's system, for example through the REST API. The sender's 200 response alone is not enough.

What if the plant network blocks outgoing traffic?

InnerWeb outgoing webhooks can be queued in an outbox table, and a poller collects the batch over an incoming channel. This solution is for sending from the platform and must be agreed with IT.

Let us check that the events from access control arrive

Let us talk about the webhook specification for your access control system and about a test that will confirm the delivery of events.

Let's talk