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
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