Back to blog
Technical

Connecting your attendance devices to Mawered: a guide by device type

Biometric terminals, access-control systems or any device through the open API: how each type of device sends its punches to Mawered, and what the API expects.

9 min readNovember 14, 2026
AZ
Amine ZaghdoudiLinkedIn

Co-founder & CTO, Mawered

Amine has been architecting Mawered's multi-country HRIS since its founding. He specialises in biometric system integration and regulatory payroll engines.


Mawered works with your attendance devices: biometric terminals, access-control systems and any device through the open API. You don't need to change hardware or pick a single brand for all your sites. This guide covers, device type by device type, how punches reach Mawered and what you need to set up.

Overview: three ways to connect a device

Device type How punches arrive What you set up
ZKTeco terminals (attendance or access-control mode) The terminal itself sends its punches to your Mawered address. The terminal in Mawered, then the server address on the terminal.
Other biometric terminals and access-control systems The vendor's software or an integration partner forwards punches to Mawered's open webhook API. A webhook source in Mawered and its API key, then the sending side in the software or at the partner.
Attendance software, middleware or another HRIS The software calls the open webhook API directly. A webhook source and its API key.

Whichever path you use, each punch is matched to the employee by their registration number, then feeds daily attendance, planning and payroll the same way.

1. ZKTeco terminals

ZKTeco terminals that support the ADMS protocol send their punches directly to your Mawered address (your subdomain). The full walkthrough, from prerequisites to troubleshooting, is in the ZKTeco integration guide. Two operating modes are accepted, side by side in the same company:

Attendance mode

The terminal works as a time clock: the employee identifies (fingerprint, face, badge or code) and the terminal records a check-in or a check-out. Each punch reaches Mawered with its direction.

Access-control mode

The terminal controls a door. Mawered keeps only granted accesses of an identified employee and turns them into punches:

  • A granted access has no in/out direction: the first punch of the day is the entry and the last one the exit.
  • Denied attempts, door states and alarms create no punch.
  • The same employee passing the same terminal again less than 60 seconds after their last punch creates no new punch.

In Mawered, each terminal's mode is shown in Devices → Management (https://<your-subdomain>.mawered.com/devices), next to its vendor.

2. Other biometric terminals and access-control systems

Other devices connect through Mawered's open webhook API. Most vendors offer a way to read events from their devices: management or access-control software with an API, a cloud platform, or HTTP event push from the device itself. The vendor's software, or an integration partner, reads those events and forwards them to Mawered in the format described below.

Brands you can connect to Mawered include ZKTeco, Hikvision, Suprema, Anviz, Matrix COSEC, Dahua, Paxton, Nedap and TimeTec. Other systems connect through Mawered's open API.

To get started, gather three things: the software or platform you use with your devices, the person or partner who can set up an HTTPS push in it, and the list of your employees' registration numbers as stored on the devices.

3. Create a webhook source in Mawered

These settings are reserved for users with the Configure terminals permission (terminals:configure).

  1. In Devices → Management (https://<your-subdomain>.mawered.com/devices), turn on the Webhook sources switch. While it is off for your company, the API answers 403 and stores nothing.
  2. Click Add webhook source, give it a name (e.g. "Access-control gateway - Head office") and pick its site.
  3. Mawered shows the source's API key only once. Copy it and pass it to the person setting up the push.

Each source has its own key. You can rotate or revoke it at any time from the source's details: the old key stops working immediately.

4. What the API expects

Punches are sent over HTTPS, in batches, to the following address:

POST https://your-subdomain.mawered.com/api/v1/devices/punches/
Authorization: Bearer <the source's API key>
Content-Type: application/json
{
  "punches": [
    { "event_id": "evt-0001", "user_id": "1042", "timestamp": "2026-11-14T08:00:00+01:00", "direction": "in" },
    { "event_id": "evt-0002", "user_id": "1042", "timestamp": "2026-11-14T17:00:00+01:00", "direction": "out", "verification_mode": "face" }
  ]
}
  • One key per source: the key identifies the source and your company. A missing, wrong or revoked key gets a 401 response; while webhook sources are disabled, the response is 403 and nothing is stored.
  • event_id: a unique id of the punch within the source. Sending the same event_id again creates no duplicate: Mawered answers that the punch was already received. You can therefore resend a batch safely after a network outage.
  • user_id: the employee's registration number in Mawered, as a string or an integer.
  • timestamp: the date and time in ISO 8601 format with its UTC offset (for example +01:00, or Z for UTC). A timestamp without an offset is refused.
  • direction: in for a check-in, out for a check-out. verification_mode (fingerprint, face, card…) is optional.
  • Limits: 1 to 500 punches per request, a request body of at most 2 MiB (beyond that, a 413 response and nothing is stored), and about 60 requests per minute per key. On a 429 response, always wait for the time given in the Retry-After header instead of counting your requests yourself. A batch containing an invalid punch is refused as a whole (422 response naming the punches at fault).
  • Concurrent sends: if the same event_id is sent twice at the same time, one of the requests may get a 503 response with a Retry-After header; resend the batch then, with no risk of duplicates.

The response lists, for each event_id, what happened: stored (punch stored), duplicate (same employee and time as a punch already present) or already_received (event_id already received; original_outcome then gives the result of the first delivery):

{
  "results": [
    { "event_id": "evt-0001", "outcome": "stored" },
    { "event_id": "evt-0002", "outcome": "already_received", "original_outcome": "stored" }
  ]
}

Time zone

Mawered converts each timestamp and stores it in the terminal's local time (the time zone set on the source), else in the time zone configured for the site's company, else in UTC. Administrators should therefore set the company time zone.

Stored punches show up in Time Tracking (https://<your-subdomain>.mawered.com/pointages) and in device monitoring like those of any other terminal.

Good practices

  • Check registration numbers before connecting a device. A number stored as "042" on the device and "42" in Mawered will not be matched to the right employee.
  • One source per system. Create a separate webhook source for each software or site that sends punches: you can revoke one key without cutting off the others.
  • Send the actual punch time, not the time of sending, with its UTC offset: it is what lateness and worked hours are calculated from.

See also: ZKTeco integration guide — Absence management and biometric time tracking for SMEs — Time tracking management module (https://<your-subdomain>.mawered.com/pointages)


Ready to automate your HR?

Mawered is built for companies in the MENA region. Compliant payroll, attendance from biometric terminals, access-control systems or any device through the open API, absence and planning management in one tool.

Request a free demo
Labour Law Compliant · TNCNSS · IR · IPP TunisiaQatar GOSI ReadyHTTPS/TLS · Bcrypt · RBAC99.9% SLA Uptime
© 2026 Teknovat · Mawered. All rights reserved.
All systems operational