ZKTeco Push Protocol Explained
A deep dive into how ZKTeco devices communicate using the push protocol — packet structure, handshake flow, and why most open-source libraries get it wrong.
What is the push protocol?
The ZKTeco push protocol (sometimes called PUSH SDK or iclock protocol) is a mechanism where the biometric device initiates the connection to a server, rather than the server polling the device. This is fundamentally different from the pull-based SDK approach.
In push mode, the device sends HTTP requests to a configured server address at regular intervals, carrying attendance logs, device status, and responding to commands. This makes it ideal for cloud deployments.
Packet structure
Each push request from the device contains a specific URL pattern and form-encoded data. The handshake starts with a GET request to /iclock/cdata, which the server responds to with device configuration parameters.
Subsequent requests include attendance data (POST to /iclock/cdata), device info (GET to /iclock/getrequest), and command results (POST to /iclock/devicecmd).
The handshake flow
1. Device boots and sends GET /iclock/cdata?SN=XXXX to the server
2. Server responds with configuration: Stamp, OpStamp, ErrorDelay, Delay, TransTimes, TransInterval, TransFlag, and Realtime
3. Device begins sending attendance data at the configured interval
4. Between data pushes, device polls GET /iclock/getrequest for pending commands
5. Device executes commands and reports results via POST /iclock/devicecmd
Why open-source libraries fail
Most open-source ZKTeco libraries implement the pull-based UDP protocol, not the push protocol. The few that attempt push protocol support typically have issues with: incomplete handshake implementation, missing command queuing, no retry logic for failed deliveries, and inability to handle multiple devices simultaneously.
PunchConnect's protocol engine handles all of this — battle-tested with 80+ devices pushing data concurrently in production.
Conclusion
Understanding the push protocol is key to building reliable biometric integrations. PunchConnect abstracts all this complexity behind a clean REST API and webhook system, so you never have to deal with raw protocol packets.