Deep-dive

ZKTeco Push Protocol Explained: Why It Matters for Cloud Attendance

ZKTeco devices support two connection modes: pull (SDK) and push (cloud). Learn how push mode eliminates static IPs, local servers, and polling — and how to get real-time attendance data through a REST API.

PunchConnect Team·Mar 27, 2026·10 min read

Introduction

You bought a ZKTeco device. You connected it to the network. Now you need attendance data in your cloud application. The question is: does the device push data to you, or do you pull it from the device?

That one architectural decision — push vs. pull — determines whether your integration works reliably at scale or breaks the moment you add a second office. Most developers start with the pull approach (SDK libraries), hit a wall, and then discover push mode exists. By then, they've already burned weeks.

This article explains what push mode is, why it exists, how it compares to the SDK approach, and how to get real-time attendance data without touching raw device protocols.

Pull Mode: The SDK Approach (and Why It Breaks)

The traditional way to get data from a ZKTeco device is pull mode. Your server connects to the device over the local network, authenticates, and requests records. Libraries like pyzk, node-zklib, and zklib all work this way.

It feels simple at first. Write a script, connect to the device IP, call get_attendance(), done. But the simplicity is deceptive.

Here's what goes wrong in production:

- Your app runs in the cloud. AWS, Azure, Railway, Vercel — none of these can reach a device behind a router on a corporate LAN. You need a local server running 24/7 as a bridge.
- Devices get new IPs. IT resets the router, DHCP lease expires, someone unplugs the switch. Your connection string is now wrong, and you're not getting data until someone notices.
- Polling isn't real-time. You're asking the device "any new records?" every 30 seconds. That's bandwidth wasted on empty responses 95% of the time — and a 30-second delay when data does arrive.
- It doesn't scale. Managing persistent connections to 50+ devices across multiple offices, each with its own network configuration? That's a full-time ops job.

Pull mode works for a single device on a LAN. The moment you go multi-site or cloud-based, you need push mode.

Push Mode: The Device Connects to You

Push mode flips the connection direction. The device initiates the connection to a cloud server, not the other way around. The device doesn't need a static IP. Your server doesn't need to be on the same network. The device just needs internet access.

In push mode, the device does the heavy lifting. It connects outbound to the cloud, sends attendance data as events happen, receives commands (sync time, enroll users, restart), and reports its status — all without your server ever needing to initiate a connection.

This is how ZKTeco devices are meant to work in cloud environments. Most modern ZKTeco devices (manufactured after 2015) support push mode out of the box. You configure the server address in the device settings, and it starts pushing.

Why Push Mode Wins

| Factor | Pull (SDK) | Push (Cloud) |
|--------|-----------|--------------|
| Network requirement | Same LAN | Internet only |
| Device IP | Static required | Any (DHCP fine) |
| Latency | 30s–5min polling delay | Real-time (<1s) |
| Cloud apps | ❌ Needs local bridge | ✅ Native |
| Multi-site | ❌ VPN per site | ✅ All push to one endpoint |
| Scaling | 1 thread per device | Event-driven, no polling |
| Firewall | Inbound ports open | Outbound only (like a browser) |

The Hard Part: Building a Push Protocol Server

Here's where most teams get stuck. Push mode is better, but implementing the server that receives push data is complex. The device speaks a proprietary protocol. You need to:

- Parse the device's connection handshake correctly
- Handle authentication and device registration
- Process attendance records from the raw data format
- Queue and deliver commands back to the device
- Manage connection state for dozens of devices simultaneously
- Handle reconnections, timeouts, and data deduplication
- Store and replay records when your downstream system is offline

This is not a weekend project. Open-source attempts exist, but most handle only basic attendance fetching and break under load. Building a production-grade push protocol server took our team months of work and thousands of hours of testing with 80+ devices in the field.

You have two options:

1. Build it yourself — plan 3-6 months of protocol engineering
2. Use a middleware that already handles the protocol and gives you a clean API

The Middleware Approach: Protocol In, REST API Out

PunchConnect sits between your devices and your application. Devices push data to PunchConnect's protocol engine. You consume clean REST API endpoints and webhooks. You never touch the raw protocol.

Getting Real-Time Attendance Data (Code Examples)

Once your device is configured in the PunchConnect dashboard (takes about 5 minutes), you interact exclusively with the REST API. Here's how to get attendance data:

Fetch Recent Attendance Records

Response:

bash

# Get today's attendance events
curl -X GET "https://api.punchconnect.com/v1/attendance?from=2026-03-27T00:00:00Z" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Python — Fetch and Process Attendance

python

import requests
from datetime import datetime, timezone

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.punchconnect.com/v1"

def get_attendance(from_date: str = None):
    """Fetch attendance records from PunchConnect."""
    params = {}
    if from_date:
        params["from"] = from_date

    response = requests.get(
        f"{BASE_URL}/attendance",
        headers={"Authorization": f"Bearer {API_KEY}"},
        params=params,
    )
    response.raise_for_status()
    return response.json()["data"]


def sync_to_your_system(records):
    """Push attendance records to your HR system."""
    for record in records:
        print(
            f"[{record['punch_time']}] "
            f"{record['employee_id']} — "
            f"{record['punch_type']} "
            f"({record['verify_mode']})"
        )
        # your_hr_system.create_attendance(
        #     employee=record["employee_id"],
        #     timestamp=record["punch_time"],
        #     type=record["punch_type"],
        # )


if __name__ == "__main__":
    today = datetime.now(timezone.utc).strftime("%Y-%m-%dT00:00:00Z")
    records = get_attendance(from_date=today)
    print(f"Fetched {len(records)} records")
    sync_to_your_system(records)

JavaScript — Real-Time Webhook Listener

Instead of polling the API, you can receive instant webhook notifications the moment a punch happens:

javascript

import express from "express";

const app = express();
app.use(express.json());

app.post("/webhook/attendance", (req, res) => {
  const event = req.body;

  // Verify the webhook signature (recommended)
  // verifySignature(req.headers["x-punchconnect-signature"], req.body);

  console.log(`New punch: ${event.employee_id} at ${event.punch_time}`);
  console.log(`  Type: ${event.punch_type} | Method: ${event.verify_mode}`);
  console.log(`  Device: ${event.device_serial}`);

  // Process in your system
  // await hrSystem.recordAttendance(event);

  res.status(200).json({ received: true });
});

app.listen(3000, () => {
  console.log("Webhook listener running on port 3000");
});

Check Device Status

bash

# See all devices and their connection status
curl -X GET "https://api.punchconnect.com/v1/devices" \
  -H "Authorization: Bearer YOUR_API_KEY"

Which ZKTeco Devices Support Push Mode?

Most modern ZKTeco devices support push mode. Any device running ZMM firmware (the majority of devices manufactured after 2015) has push capability. This includes:

- Face recognition: SpeedFace V5L, SpeedFace-H5, ProFace X
- Fingerprint: UA860, K40, IN01-A, X7
- Multi-modal: SpeedFace V4L, MultiBio 800
- Access control: inBio 160/260, C3-100/200/400

How to check: Look for the "Cloud Server" or "ADMS Server" setting in your device's network configuration menu. If it's there, your device supports push mode.

Configuring push mode in PunchConnect: You register your device in the dashboard, get a server address, enter it in the device settings, and the device starts pushing. The entire process takes about 5 minutes per device. No software installation, no SDK, no local server.

Push Mode vs. Pulling with SDK Libraries: A Real Comparison

We've deployed both approaches in production. Here's what we've seen:

A logistics company with 12 offices started with pyzk running on a Raspberry Pi at each site. Maintenance cost: one full-time engineer managing 12 Pis, troubleshooting network changes, restarting crashed scripts, and dealing with data gaps when Pis went offline. After switching to push mode with PunchConnect: zero on-site infrastructure, 99.5% data delivery rate, and the engineer was reassigned to product work.

An agriculture company (AgriWise) with 24,000+ employees across 50+ sites needed real-time attendance in their ERP. Pull mode was never an option — you can't maintain persistent connections to 80+ devices across a country. Push mode with PunchConnect handles all of it from a single cloud endpoint. Read the full case study →

The pattern is clear: pull mode works for prototypes, push mode works for production.

Common Questions About Push Mode

Do I need to open firewall ports for push mode?

No. Push mode uses outbound connections from the device, just like a web browser. If your device can access the internet, it can push data. No inbound ports, no static IP, no port forwarding needed.

How real-time is push mode?

Sub-second. When an employee punches on the device, the event reaches PunchConnect and triggers your webhook within 1 second. Compared to SDK polling (30 seconds to 5 minutes), push mode is effectively instant.

What happens if the internet goes down?

The device buffers locally. ZKTeco devices store records in onboard memory (typically 50,000–100,000 records). When connectivity returns, the device automatically pushes all buffered records. PunchConnect deduplicates them, so you never get duplicate entries.

Can I send commands back to the device in push mode?

Yes. PunchConnect queues commands (enroll employees, sync time, restart, update settings) and delivers them to the device on the next push cycle. You send commands via the REST API, and PunchConnect handles delivery.

bash

# Enroll an employee on a device
curl -X POST "https://api.punchconnect.com/v1/devices/BFEZ203901245/commands" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "enroll_employee",
    "params": {
      "employee_id": "emp_099",
      "name": "Sarah Johnson",
      "card_number": "0012345678"
    }
  }'

Is push mode compatible with all ZKTeco models?

Push mode works with any ZKTeco device that has the "Cloud Server" or "ADMS Server" setting — which is the vast majority of devices made after 2015. Older devices (pre-2015) may only support pull mode, but these are increasingly rare in active deployments.

Getting Started

If you're building a biometric integration and trying to decide between push and pull:

1. Start with push mode. It's the right architecture for any cloud-based application.
2. Don't build the protocol server yourself — unless you have months to spare and deep experience with ZKTeco device protocols.
3. Try PunchConnect free for 7 days — register your device, get your API key, and receive your first attendance webhook in under 15 minutes. No credit card required.

If you're already using an SDK library and hitting scaling issues, read our comparison: Why Open-Source ZKTeco Libraries Won't Scale. And if your biggest blocker is the static IP requirement, see Biometric Attendance Without a Static IP.

---

*PunchConnect is production-proven middleware connecting ZKTeco biometric devices to any software system. Currently powering attendance for 24,000+ employees across 50+ sites.*

Deep-dive

ZKTeco Push Protocol Explained: Why It Matters for Cloud Attendance

Introduction

Pull Mode: The SDK Approach (and Why It Breaks)

Push Mode: The Device Connects to You

Why Push Mode Wins

The Hard Part: Building a Push Protocol Server

The Middleware Approach: Protocol In, REST API Out

Getting Real-Time Attendance Data (Code Examples)

Fetch Recent Attendance Records

Python — Fetch and Process Attendance

JavaScript — Real-Time Webhook Listener

Check Device Status

Which ZKTeco Devices Support Push Mode?

Push Mode vs. Pulling with SDK Libraries: A Real Comparison

Common Questions About Push Mode

Do I need to open firewall ports for push mode?

How real-time is push mode?

What happens if the internet goes down?

Can I send commands back to the device in push mode?

Is push mode compatible with all ZKTeco models?

Getting Started

Related articles

Why Open-Source ZKTeco Libraries Won't Scale (And What to Use Instead)

How to Connect ZKTeco to Odoo: Cloud API Integration Guide

Biometric Attendance Without Static IP: How Cloud APIs Solve the Network Problem