InnerWeb
Skip to main content

KD Event Webhook: Integration Specification for the Integrator

The access control system records every card punch: who, where and when. An integrator describing a webhook for the permissions system sets out in the specification which fields the KD system sends, how the channel is authenticated and how the receiver treats repeated events. Below are the requirements for fields, pairing, duplicates and queuing.

5
basic event fields in the specification
Source: card
4
test cases before go-live of the integration
Source: card

What the specification requires from the KD system

The KD system sends punch events in real time. Each event carries the punch time read from the reader, the direction (entry or exit) and the event identifier, alongside the card or account identifier and the reader identifier. Thanks to the reader event time, the attendance history reflects the actual moment of passage, not the moment the message was delivered.

InnerWeb receives events from the KD system via an authenticated webhook and links them with qualifications, permits, attendance and time tracking. Rules for pairing entries and exits and rejecting duplicates are set in the specification together with the KD vendor, because they depend on reader and gate configuration at the plant. If a reader in a given KD installation does not return direction, this is a technical fact on the KD side and must be described separately in the specification.

How to describe the event in the specification

The integrator specification should be short and unambiguous. Each field has a name, type, format and a description of permitted values. It also describes authentication: a token of limited validity, renewed automatically by the integration.

  • Account or card identifier, in a form agreed between the systems.
  • Reader identifier matching the location defined in the permissions system.
  • Reader event time, with time zone, in a fixed format.
  • Direction: entry or exit, according to the reader configuration in the KD system.
  • Unique event identifier for retries and removal of repeats.

Why the reader must have a place in the system

A punch from a reader without an assigned place, that is an action point, does not trigger a training alarm. The event arrives but has no effect. Before starting the integration, check that every reader has a counterpart in the system.

KD integration specification elements

KD integration specification elementsChart: 5 event fields and 4 test cases in the integration specification.012345countEvent fieldsEvent fields: 5 count5Test casesTest cases: 4 count4
Source: Cell card: structure of the specification and tests

Pairing entries with exits and duplicates

When pairing entries with exits, the receiver joins consecutive punches of the same account into pairs and flags unpaired events for verification. The maximum gap between entry and exit should be chosen to match the plant's work organisation, with a margin for overtime and breaks. The specific value and the handling of unpaired events are set in the specification with the KD vendor.

Pairing is a method, not proof: the report should show which pairs result from the rule and which come directly from the reader. This keeps attendance and time tracking control clear for audit.

Repeated punches

An employee presents the card twice because the gate did not open at once. The specification should define how closely consecutive punches of the same card on the same reader are treated, so that the number of punches within a shift does not become odd and the pairs do not drift apart. The time threshold is agreed with the KD vendor.

Plant network and the outbox queue

The plant network may be configured so that the application server cannot send traffic outside. Outgoing webhooks can then be queued in an outbox table, and receipt happens through another channel agreed with the client. The integrator describes this channel in the specification, together with the maximum delivery delay.

From the integrator's perspective, idempotency is important: the same event sent twice must not become two punches. The unique event identifier solves this problem.

Account safety when linking events

The system never links or redirects an active account based solely on similarity of surname, and accounts with a card are shown first in the list. KD events therefore reach the correct account by identifier, not by surname.

It is worth agreeing with the KD vendor that the identifier in the event is stable and does not change when a card is replaced. Then migrating cards to new technology does not break the punch history.

Tests before going live

Before go-live, check four cases. First: an entry and an exit punch in the same shift create a pair. Second: a repeated punch within a short interval counts as one. Third: sending the same event twice with the same identifier does not create a duplicate. Fourth: a punch from a reader without a place in the system is reported as a configuration error.

Record the test results in the integration acceptance protocol. The integrator and the client then have shared evidence that the webhook works according to the specification, and if a dispute arises, events can be reproduced from the log.

Video

Frequently asked questions

What data should a KD event contain?

Reader event time, direction (entry or exit), event identifier, card or account identifier and reader identifier.

Why is a unique event identifier needed?

It allows retries without the risk of creating two punches. The receiver removes repeats based on this identifier.

What if the server cannot reach the external network?

Webhooks can be queued in an outbox table, and receipt takes place through another channel agreed with the client.

Webhook specification for your integrator

We will prepare with you a description of fields, pairing and queuing of KD events. Book a call with the InnerWeb team.

Let's talk