Tutorial

Setting Up Biometric Webhooks Without a Static IP

Your biometric devices shouldn't need a static IP or a local server. Learn how to set up cloud webhooks that push real-time attendance data to any endpoint — with production-ready code in Node.js, Python, and cURL.

PunchConnect Team·Mar 27, 2026·9 min read

Introduction

Your biometric device sits in an office lobby. Your application runs on AWS. The device can't reach your server, and your server can't reach the device. That's the fundamental problem every team hits when they try to get real-time attendance data into their cloud app.

The traditional fix — a local server with a static IP running 24/7 — was designed for a world where applications lived on-premise. In 2026, your app runs on Vercel, Railway, Render, or a Kubernetes cluster. You need webhooks, not polling loops.

This guide walks you through setting up biometric webhooks with PunchConnect. From zero to receiving live punch events in under 15 minutes. No static IP. No VPN. No local server.

How Biometric Webhooks Work

A webhook is just an HTTP POST request that PunchConnect sends to your server every time something happens — an employee punches in, a new fingerprint is enrolled, or a device goes offline. You give PunchConnect a URL, and it pushes events to you in real time.

The key difference from traditional setups: your server doesn't poll. It doesn't connect to the device. It just listens for incoming HTTP requests like any normal web endpoint.

Here's what happens step by step:

1. Employee punches on the biometric device (fingerprint, face, card)
2. Device pushes the event to PunchConnect's protocol engine (outbound from the device — no static IP needed)
3. PunchConnect normalizes the raw device data into a clean JSON payload
4. Webhook fires — PunchConnect sends an HTTP POST to your registered callback URL
5. Your app processes the event (update database, trigger workflow, send notification)

If your endpoint returns a 5xx error or times out, PunchConnect automatically retries with exponential backoff for up to 72 hours. No punch data is lost.

Step 1: Create Your Webhook Endpoint

Your webhook endpoint is just a normal HTTP route that accepts POST requests. Here's the simplest version in three languages:

Node.js (Express):

Python (Flask):

```python
from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhook/attendance', methods=['POST'])
def handle_punch():
data = request.json
employee_id = data['employee_id']
timestamp = data['timestamp']
punch_type = data['punch_type']

print(f"Punch received: Employee {employee_id} at {timestamp}")

# Your logic: save to DB, notify manager, update ERP...

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

if __name__ == '__main__':
app.run(port=3000)
```

Deploy this to any cloud platform — Vercel, Railway, Render, Heroku, AWS Lambda, a VPS, anything with a public URL. That URL becomes your callback.

javascript

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

app.post('/webhook/attendance', (req, res) => {
  const { event_id, employee_id, timestamp, device_serial, punch_type } = req.body;

  console.log(`Punch received: Employee ${employee_id} at ${timestamp}`);

  // Your logic: save to DB, notify manager, update ERP...

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

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

Step 2: Register Your Webhook with PunchConnect

Use the PunchConnect API to tell the system where to send events:

The secret field is critical — PunchConnect uses it to sign every webhook payload so you can verify authenticity. More on that in the security section.

Response:

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.railway.app/webhook/attendance",
    "events": ["attendance.punch"],
    "secret": "your-webhook-secret-here"
  }'

Step 3: Configure Your Device

Add your biometric device to PunchConnect through the dashboard. The device connects outbound to PunchConnect's cloud — no port forwarding, no static IP, no VPN.

The setup takes about 5 minutes per device in the dashboard:

1. Add the device (serial number + model)
2. Point the device's server address to PunchConnect's endpoint
3. The device auto-connects and starts pushing data
4. PunchConnect forwards events to your registered webhook

That's it. No firewall rules. No static IP. No port forwarding.

Step 4: Verify Webhook Signatures

Never trust an incoming webhook blindly. PunchConnect signs every payload using HMAC-SHA256 with your webhook secret. Always verify before processing.

Node.js verification:

Python verification:

```python
import hmac
import hashlib
import json

def verify_signature(payload, signature, secret):
expected = hmac.new(
secret.encode(),
json.dumps(payload, separators=(',', ':')).encode(),
hashlib.sha256
).hexdigest()
return hmac.compare_digest(signature, expected)

@app.route('/webhook/attendance', methods=['POST'])
def handle_punch():
signature = request.headers.get('X-PunchConnect-Signature')
if not verify_signature(request.json, signature, 'your-webhook-secret'):
return jsonify({"error": "Invalid signature"}), 401

# Safe to process
data = request.json
# ... your logic
return jsonify({"received": True}), 200
```

javascript

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

app.post('/webhook/attendance', (req, res) => {
  const signature = req.headers['x-punchconnect-signature'];

  if (!verifyWebhookSignature(req.body, signature, 'your-webhook-secret')) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Safe to process — verified from PunchConnect
  const { employee_id, timestamp, punch_type } = req.body;
  // ... your logic
  res.status(200).json({ received: true });
});

Step 5: Handle Retries and Idempotency

PunchConnect retries failed deliveries with exponential backoff: 1 min → 5 min → 15 min → 1 hour → 4 hours, continuing for up to 72 hours. This means your endpoint might receive the same event twice in edge cases (network timeout after your server processed but before PunchConnect got the 200 response).

Always implement idempotency using the `event_id` field:

In production, store processed event IDs in Redis (with a 72-hour TTL) or a database table. A simple Set works for testing.

javascript

const processedEvents = new Set(); // Use Redis or DB in production

app.post('/webhook/attendance', (req, res) => {
  const { event_id } = req.body;

  if (processedEvents.has(event_id)) {
    return res.status(200).json({ received: true, duplicate: true });
  }

  processedEvents.add(event_id);

  // Process the event...
  res.status(200).json({ received: true });
});

Testing Your Webhook Locally

Before deploying, test locally using PunchConnect's test endpoint or a tool like ngrok to expose your local server:

The test endpoint simulates a real punch event, so you can verify your entire pipeline without a physical device.

bash

# Start your local server
node server.js

# Expose it with ngrok
ngrok http 3000
# → https://abc123.ngrok.io

# Register the ngrok URL as your webhook
curl -X POST https://api.punchconnect.com/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://abc123.ngrok.io/webhook/attendance", "events": ["attendance.punch"]}'

# Trigger a test event
curl -X POST https://api.punchconnect.com/v1/webhooks/wh_abc123/test \
  -H "Authorization: Bearer YOUR_API_KEY"

Webhook Payload Reference

Every attendance webhook delivers a consistent JSON structure:

Key fields:
- `event_id` — unique per event, use for idempotency
- `punch_type` — check_in, check_out, break_start, break_end
- `verification_method` — fingerprint, face, card, pin
- `signature` — HMAC-SHA256 of the payload for verification

json

{
  "event_id": "evt_7f8a9b2c",
  "event_type": "attendance.punch",
  "timestamp": "2026-03-27T08:02:14Z",
  "device": {
    "serial": "CWE2203900045",
    "name": "Lobby Terminal",
    "site": "HQ Building A"
  },
  "employee": {
    "id": "142",
    "name": "Sarah Chen"
  },
  "punch_type": "check_in",
  "verification_method": "fingerprint",
  "webhook_id": "wh_abc123",
  "signature": "a1b2c3d4e5f6..."
}

Production Checklist

Before going live, make sure you've covered these:

- ✅ HTTPS endpoint — PunchConnect won't deliver to plain HTTP in production
- ✅ Signature verification — validate every request with HMAC-SHA256
- ✅ Idempotency — handle duplicate deliveries using event_id
- ✅ 200 response within 10 seconds — return quickly, process async if needed
- ✅ Logging — record every webhook for debugging (PunchConnect dashboard also shows delivery logs)
- ✅ Alerting — monitor for delivery failures in PunchConnect's webhook logs

If your endpoint needs more than 10 seconds to process, return 200 immediately and process the event asynchronously in a background queue (SQS, BullMQ, Celery).

Frequently Asked Questions

Do I need a static IP to receive webhooks?

No. That's the entire point. Your webhook endpoint just needs a public URL — any cloud platform (AWS, Railway, Vercel, Render) provides this automatically. The device connects outbound to PunchConnect, and PunchConnect connects outbound to your URL. No inbound connections required.

What happens if my server is down when a punch happens?

PunchConnect queues the event and retries with exponential backoff for up to 72 hours. Once your server comes back online, all queued events are delivered in order. Zero data loss.

Can I receive webhooks on a serverless function?

Yes. PunchConnect webhooks work with AWS Lambda, Vercel Functions, Cloudflare Workers, Google Cloud Functions — any platform that can receive HTTP POST requests. Just make sure your function responds within 10 seconds.

How do I debug failed webhook deliveries?

The PunchConnect dashboard shows a complete delivery log for every webhook: request body, response code, response time, and retry history. You can also replay any failed delivery with one click.

Tutorial

Setting Up Biometric Webhooks Without a Static IP

Introduction

How Biometric Webhooks Work

Step 1: Create Your Webhook Endpoint

Step 2: Register Your Webhook with PunchConnect

Step 3: Configure Your Device

Step 4: Verify Webhook Signatures

Step 5: Handle Retries and Idempotency

Testing Your Webhook Locally

Webhook Payload Reference

Production Checklist

Frequently Asked Questions

Do I need a static IP to receive webhooks?

What happens if my server is down when a punch happens?

Can I receive webhooks on a serverless function?

How do I debug failed webhook deliveries?

Related articles

How to Connect ZKTeco to Odoo: Cloud API Integration Guide

ZKTeco Webhook Integration: Real-Time Attendance Pipelines via REST API

Fingerprint Device API Integration: A Developer's Guide to Cloud Biometric Connectivity

Introduction

How Biometric Webhooks Work

Step 1: Create Your Webhook Endpoint

Step 2: Register Your Webhook with PunchConnect

Step 3: Configure Your Device

Step 4: Verify Webhook Signatures

Step 5: Handle Retries and Idempotency

Testing Your Webhook Locally

Webhook Payload Reference

Production Checklist

Related Guides

Frequently Asked Questions

Do I need a static IP to receive webhooks?

What happens if my server is down when a punch happens?

Can I receive webhooks on a serverless function?

How do I debug failed webhook deliveries?

Can I subscribe to multiple event types?

Related articles

How to Connect ZKTeco to Odoo: Cloud API Integration Guide

ZKTeco Webhook Integration: Real-Time Attendance Pipelines via REST API

Fingerprint Device API Integration: A Developer's Guide to Cloud Biometric Connectivity