Engineering

Designing a Biometric Attendance API That Developers Actually Want to Use

Q: Can I replay historical webhook events?

Yes. The [webhook management API](/blog/webhook-setup-cloud-guide) lets you replay events for a given time range. Useful for backfilling data after fixing a bug in your handler.

Q: How do I test webhooks during development?

Register a webhook URL pointing to a tool like [ngrok](https://ngrok.com) or [webhook.site](https://webhook.site). PunchConnect will deliver real events from your test devices to your local machine.

Most biometric APIs are afterthoughts bolted onto hardware SDKs. Here's how we designed PunchConnect's REST API from first principles — with webhooks, idempotency, and real-time delivery that developers expect from modern infrastructure.

PunchConnect Team·Mar 28, 2026·10 min read

Introduction

You've built an HRMS. Payroll runs on attendance data. Now you need to get punch events from 200 biometric devices into your system — reliably, in real time, without losing a single record. That's the API design problem nobody talks about until they're debugging missing punches at 2 AM.

Most biometric "APIs" are vendor SDKs dressed in REST clothing. They expose raw device registers, require polling loops, and break when a device goes offline for 30 seconds. They weren't designed for cloud-native applications.

When we built PunchConnect's API, we started from the other end: what would a developer building an ERP integration expect? The answer looked a lot like Stripe, Twilio, and GitHub — not like a hardware manual.

Three Design Principles We Stole From the Best

We studied the APIs developers actually enjoy using. Three patterns kept showing up:

1. Be predictable. Every endpoint follows the same naming convention. Every response has the same shape. Every error returns a structured object with a machine-readable code and a human-readable message. No surprises.

2. Be real-time. Webhooks for events, not polling. When an employee punches in at the door, your application knows within seconds — not whenever your cron job runs.

3. Be resilient. Every mutating operation accepts an idempotency key. Every webhook delivery retries with exponential backoff. Every piece of data can be replayed without duplicates.

The Webhook Delivery Pipeline

The hardest part of a biometric attendance API isn't the REST endpoints — it's guaranteeing delivery of punch events when the real world is unreliable. Devices go offline. Networks drop. Servers restart during deployments.

PunchConnect guarantees at-least-once delivery for every webhook event. Here's exactly how:

1. Punch event occurs on the biometric device (fingerprint, face, card)
2. Event is persisted to a durable queue — it's safe even if the entire system restarts
3. Delivery worker sends an HTTP POST to your registered callback URL
4. Your server responds with 2xx → event marked as delivered
5. If delivery fails (5xx, timeout, network error) → exponential backoff retries over 72 hours
6. After all retries exhausted → event marked as failed, email notification sent to your account

This is the same pattern Stripe uses for payment webhooks. The difference: our payloads contain punch events instead of charges.

What the Webhook Payload Looks Like

Every webhook delivers a clean, normalized JSON object. No raw device registers. No vendor-specific formats. Just the data your application needs:

Notice what's absent: no raw TCP register values, no hex-encoded timestamps, no device-specific command codes. PunchConnect normalizes all of that before it reaches your webhook. You work with clean employee names, badge numbers, and ISO timestamps.

json

{
  "event_id": "evt_a1b2c3d4e5f6",
  "event_type": "attendance.punch",
  "timestamp": "2026-03-28T08:01:23Z",
  "device": {
    "id": "dev_9x8y7z",
    "serial_number": "BKRK233600045",
    "name": "Main Entrance",
    "site": "Headquarters"
  },
  "employee": {
    "id": "emp_4k5l6m",
    "badge_number": "1042",
    "name": "Sarah Chen"
  },
  "punch": {
    "direction": "in",
    "method": "fingerprint",
    "confidence": 0.97,
    "local_time": "2026-03-28T09:01:23+01:00"
  },
  "metadata": {
    "deduplicated": false,
    "delivery_attempt": 1
  }
}

Handling Webhook Events in Your Application

Here's how you receive and process attendance webhooks in your backend:

Python (Flask)

python

import hmac
import hashlib
from flask import Flask, request, jsonify

app = Flask(__name__)
WEBHOOK_SECRET = "whsec_your_signing_secret"

def verify_signature(payload, signature):
    expected = hmac.new(
        WEBHOOK_SECRET.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

@app.route("/webhooks/attendance", methods=["POST"])
def handle_attendance():
    signature = request.headers.get("X-PunchConnect-Signature")
    if not verify_signature(request.data, signature):
        return jsonify({"error": "Invalid signature"}), 401

    event = request.json
    event_type = event["event_type"]

    if event_type == "attendance.punch":
        employee = event["employee"]["badge_number"]
        direction = event["punch"]["direction"]
        timestamp = event["timestamp"]
        # Insert into your attendance table
        print(f"Employee {employee} punched {direction} at {timestamp}")

    return jsonify({"received": True}), 200

Node.js (Express)

javascript

const express = require('express');
const crypto = require('crypto');
const app = express();

const WEBHOOK_SECRET = 'whsec_your_signing_secret';

app.post('/webhooks/attendance', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-punchconnect-signature'];
  const expected = `sha256=${crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex')}`;

  if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const event = JSON.parse(req.body);

  if (event.event_type === 'attendance.punch') {
    const { badge_number } = event.employee;
    const { direction } = event.punch;
    console.log(`Employee ${badge_number} punched ${direction} at ${event.timestamp}`);
    // Save to your database
  }

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

app.listen(3000, () => console.log('Webhook listener running on :3000'));

cURL — Register Your Webhook

bash

curl -X POST https://api.punchconnect.com/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/attendance",
    "events": ["attendance.punch", "device.status"],
    "secret": "whsec_your_signing_secret"
  }'

Idempotency: Why Every Command Is Safe to Retry

Network failures happen. Your request times out. Did the device receive the command or not? Without idempotency, you're guessing.

PunchConnect accepts an Idempotency-Key header on every mutating endpoint. Send the same request with the same key within 24 hours, and you get the cached response — no duplicate side effects.

If your network drops before you receive the response, retry with the exact same Idempotency-Key. PunchConnect recognizes the duplicate and returns the original response. The device won't receive a double sync.

This matters most for device commands — syncing employee lists, updating access rules, triggering door locks. Without idempotency, a single retry could enroll employees twice or trigger a door open command multiple times.

bash

# Send a sync command — safe to retry
curl -X POST https://api.punchconnect.com/v1/devices/dev_9x8y7z/commands \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: sync-employees-2026-03-28-001" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "sync_employees",
    "payload": {
      "employees": [
        {"badge_number": "1042", "name": "Sarah Chen"},
        {"badge_number": "1043", "name": "James Okoro"}
      ]
    }
  }'

Rate Limiting That Doesn't Surprise You

Every response includes rate limit headers:

When you hit the limit, you get a 429 Too Many Requests with a Retry-After header telling you exactly how many seconds to wait. No guessing. No silent failures.

The defaults are generous on purpose. 1,000 REST calls per device per day covers most integration patterns. Inbound webhooks from devices to PunchConnect are unlimited — we never throttle your hardware.

text

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1711584000

Data Normalization: Cleaning Up the Mess

Here's what most teams don't realize until they're deep into a biometric integration: device data is messy. Duplicate punches when someone scans twice. Timestamps that drift by minutes across devices. Occasionally, completely garbage records from firmware bugs.

PunchConnect normalizes everything before it reaches your webhook:

- Duplicate detection — If the same employee punches on the same device within a configurable window (default: 60 seconds), the duplicate is filtered. You get one clean event.
- Timestamp normalization — Device clocks drift. PunchConnect reconciles device local time against server time and delivers UTC timestamps you can trust.
- Direction inference — Some devices don't track in/out. PunchConnect uses configurable rules (first punch = in, last punch = out, or alternating) to infer direction.
- Bad data filtering — Malformed records, zero-timestamps, and unregistered badge numbers are caught and logged without polluting your webhook stream.

You never see the raw data. That's the point.

python

# What the device actually sends (raw, messy):
# badge=1042, timestamp=1711609283, status=0, verify=1, reserved=0

# What your webhook receives (clean, normalized):
{
    "employee": {"badge_number": "1042", "name": "Sarah Chen"},
    "punch": {"direction": "in", "method": "fingerprint"},
    "timestamp": "2026-03-28T09:01:23Z"
}

REST Endpoints for Everything Else

Webhooks handle the real-time flow. For everything else — querying historical attendance, managing devices, syncing employees — there's a standard REST API:

Every list endpoint supports pagination (page, per_page), filtering, and sorting. Every response follows the same envelope:

Same shape for attendance, devices, employees, webhooks, commands. Learn it once, use it everywhere.

bash

# Get attendance records for a date range
curl https://api.punchconnect.com/v1/attendance \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -G \
  -d "start_date=2026-03-01" \
  -d "end_date=2026-03-28" \
  -d "device_id=dev_9x8y7z"

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

# Get a single device's details
curl https://api.punchconnect.com/v1/devices/dev_9x8y7z \
  -H "Authorization: Bearer YOUR_API_KEY"

What We Learned From 24,000+ Employees

Running PunchConnect across 50+ sites for AgriWise's 24,000+ employees taught us things no amount of API design theory could:

Clock drift is real. Devices across time zones and unreliable networks drift. Some by seconds, others by minutes. UTC normalization isn't optional — it's survival.

Offline buffering is mandatory. Rural agricultural sites lose internet for hours. Devices buffer punches locally. When connectivity returns, PunchConnect processes the backlog in order. Your webhook receives events with accurate timestamps, not the time they arrived at the server.

Batch operations matter. When you're syncing 5,000 employee records across 50 devices, individual API calls don't cut it. Batch endpoints with progress tracking and partial failure handling are essential.

Error messages should be copy-pasteable. When a developer hits an error, the response should contain everything they need to fix it — including a link to the relevant documentation.

Frequently Asked Questions

How fast are webhook deliveries?
Typically under 2 seconds from the moment the employee punches to your webhook receiving the event. The bottleneck is usually the device's push interval, not PunchConnect's processing.

What happens if my webhook endpoint is down for hours?
Events queue up and retry with exponential backoff over 72 hours. When your server comes back online, you'll receive all missed events in order. Nothing is lost.

Can I replay historical webhook events?
Yes. The webhook management API lets you replay events for a given time range. Useful for backfilling data after fixing a bug in your handler.

Do I need to handle duplicate webhook deliveries?
With at-least-once delivery, it's possible to receive the same event twice (e.g., if your server responded slowly and we retried). Use the event_id field for deduplication — it's unique per event and stable across retries.

How do I test webhooks during development?
Register a webhook URL pointing to a tool like ngrok or webhook.site. PunchConnect will deliver real events from your test devices to your local machine.

---

Building a biometric integration? PunchConnect gives you the API you'd design yourself — if you had six months and 24,000 employees to test against. Start a 7-day free trial and receive your first webhook in under 5 minutes. No credit card. No static IP. Just clean data, delivered reliably.

Tutorial

Designing a Biometric Attendance API That Developers Actually Want to Use

Introduction

Three Design Principles We Stole From the Best

The Webhook Delivery Pipeline

What the Webhook Payload Looks Like

Handling Webhook Events in Your Application

Python (Flask)

Node.js (Express)

cURL — Register Your Webhook

Idempotency: Why Every Command Is Safe to Retry

Rate Limiting That Doesn't Surprise You

Data Normalization: Cleaning Up the Mess

REST Endpoints for Everything Else

What We Learned From 24,000+ Employees

Frequently Asked Questions

Related articles

How to Connect ZKTeco to Odoo: Cloud API Integration Guide

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

CAMS Biometrics Alternative: Real-Time Callback API for ZKTeco Devices