Tutorial

Configurar Webhooks Biométricos Sin IP Fija

Tus dispositivos biométricos no necesitan una IP fija ni un servidor local. Aprende a configurar webhooks en la nube que envían datos de asistencia en tiempo real a cualquier endpoint — con código listo para producción en Node.js, Python y cURL.

PunchConnect Team·Mar 27, 2026·9 min read

Introduction

Tu reloj checador biométrico está en la recepción de la oficina. Tu aplicación corre en AWS. El dispositivo no puede alcanzar tu servidor, y tu servidor no puede alcanzar el dispositivo. Ese es el problema fundamental que todo equipo enfrenta cuando intenta obtener datos de asistencia en tiempo real en su aplicación en la nube.

La solución tradicional — un servidor local con IP fija corriendo 24/7 — fue diseñada para un mundo donde las aplicaciones vivían on-premise. En 2026, tu app corre en Vercel, Railway, Render o un clúster Kubernetes. Necesitas webhooks, no bucles de polling.

Esta guía te lleva paso a paso por la configuración de webhooks biométricos con PunchConnect. De cero a recibir eventos de fichaje en vivo en menos de 15 minutos. Sin IP fija. Sin VPN. Sin servidor local.

Cómo Funcionan los Webhooks Biométricos

Un webhook es simplemente una petición HTTP POST que PunchConnect envía a tu servidor cada vez que ocurre algo — un empleado ficha, se registra una nueva huella, o un dispositivo se desconecta. Le das una URL a PunchConnect y te envía los eventos en tiempo real.

La diferencia clave con las instalaciones tradicionales: tu servidor no hace polling. No se conecta al dispositivo. Simplemente escucha peticiones HTTP entrantes como cualquier endpoint web normal.

Paso a paso:

1. El empleado ficha en el dispositivo biométrico (huella, rostro, tarjeta)
2. El dispositivo envía el evento al motor de protocolo de PunchConnect (saliente desde el dispositivo — no necesita IP fija)
3. PunchConnect normaliza los datos crudos en un payload JSON limpio
4. El webhook se dispara — PunchConnect envía un HTTP POST a tu URL de callback registrada
5. Tu app procesa el evento (actualizar base de datos, activar workflow, enviar notificación)

Si tu endpoint devuelve un error 5xx o se agota el tiempo, PunchConnect reintenta automáticamente con backoff exponencial durante 72 horas. No se pierden datos de fichaje.

Paso 1: Crear Tu Endpoint Webhook

Tu endpoint webhook es simplemente una ruta HTTP normal que acepta peticiones POST:

Node.js (Express):

Python (Flask):

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

app = Flask(__name__)

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

print(f"Fichaje recibido: Empleado {employee_id} a las {timestamp}")

# Tu lógica: guardar en BD, notificar al gerente, actualizar ERP...

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

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

Despliega esto en cualquier plataforma cloud — Railway, Render, DigitalOcean, AWS Lambda, un VPS. Esa URL se convierte en tu callback.

javascript

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

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

  console.log(`Fichaje recibido: Empleado ${employee_id} a las ${timestamp}`);

  // Tu lógica: guardar en BD, notificar al gerente, actualizar ERP...

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

app.listen(3000, () => console.log('Webhook listener en el puerto 3000'));

Paso 2: Registrar Tu Webhook con PunchConnect

Usa la API de PunchConnect para indicarle al sistema dónde enviar los eventos:

El campo secret es fundamental — PunchConnect lo usa para firmar cada payload webhook para que puedas verificar la autenticidad.

bash

curl -X POST https://api.punchconnect.com/v1/webhooks \
  -H "Authorization: Bearer TU_CLAVE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://tu-app.railway.app/webhook/asistencia",
    "events": ["attendance.punch"],
    "secret": "tu-secreto-webhook"
  }'

Paso 3: Configurar Tu Dispositivo

Agrega tu dispositivo biométrico a PunchConnect a través del panel de control. El dispositivo se conecta hacia afuera al cloud de PunchConnect — sin redirección de puertos, sin IP fija, sin VPN.

La configuración toma aproximadamente 5 minutos por dispositivo:

1. Agregar el dispositivo (número de serie + modelo)
2. Apuntar la dirección del servidor del dispositivo al endpoint de PunchConnect
3. El dispositivo se conecta automáticamente y empieza a enviar datos
4. PunchConnect reenvía los eventos a tu webhook registrado

Paso 4: Verificar Firmas de Webhook

Nunca confíes en un webhook entrante ciegamente. PunchConnect firma cada payload usando HMAC-SHA256 con tu secreto webhook. Siempre verifica antes de procesar.

Esto es especialmente importante si tus clientes están en México (cumplimiento con la Ley Federal de Protección de Datos Personales) o Colombia (Ley 1581 de Habeas Data). PunchConnect firma cada evento para garantizar la integridad de los datos biométricos.

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));
}

Paso 5: Manejar Reintentos e Idempotencia

PunchConnect reintenta las entregas fallidas con backoff exponencial: 1 min → 5 min → 15 min → 1 hora → 4 horas, durante 72 horas máximo.

Siempre implementa idempotencia con el campo `event_id`:

javascript

const processedEvents = new Set(); // Usa Redis o BD en producción

app.post('/webhook/asistencia', (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);
  // Procesar el evento...
  res.status(200).json({ received: true });
});

Checklist de Producción

Antes de pasar a producción:

- ✅ Endpoint HTTPS — PunchConnect no entrega a HTTP plano en producción
- ✅ Verificación de firma — valida cada petición con HMAC-SHA256
- ✅ Idempotencia — maneja duplicados con event_id
- ✅ Respuesta 200 en menos de 10 segundos — responde rápido, procesa async si necesitas
- ✅ Registro — guarda cada webhook para depuración
- ✅ Cumplimiento normativo — documenta el tratamiento de datos biométricos según la legislación local

Guías Relacionadas

- Asistencia Biométrica Sin IP Fija — por qué las IP fijas son el enfoque equivocado
- Integración Webhook ZKTeco — configuración específica para terminales ZKTeco
- API REST de Dispositivo Biométrico — referencia API completa con ejemplos de código
- Seguridad de Datos Biométricos en Tránsito — cifrado, firmas y cumplimiento

Preguntas Frecuentes

¿Necesito una IP fija para recibir webhooks?

No. Ese es el punto. Tu endpoint webhook solo necesita una URL pública — cualquier plataforma cloud (AWS, DigitalOcean, Railway, Render) la proporciona automáticamente.

¿Qué pasa si mi servidor está caído cuando ocurre un fichaje?

PunchConnect encola el evento y reintenta con backoff exponencial durante 72 horas. Cuando tu servidor vuelva en línea, todos los eventos pendientes se entregan en orden. Cero pérdida de datos.

¿Puedo recibir webhooks en una función serverless?

Sí. Los webhooks de PunchConnect funcionan con AWS Lambda, Vercel Functions, Cloudflare Workers, Google Cloud Functions — cualquier plataforma que pueda recibir peticiones HTTP POST.

¿Cómo depuro las entregas webhook fallidas?

El panel de control de PunchConnect muestra un registro completo de cada webhook: cuerpo de la petición, código de respuesta, tiempo de respuesta e historial de reintentos. También puedes reenviar cualquier entrega fallida con un clic.

¿Funciona con los relojes checadores más comunes en Latinoamérica?

Sí. PunchConnect soporta la mayoría de dispositivos ZKTeco (incluyendo modelos populares en México, Colombia, Perú y Argentina como los de la serie MB, uFace y SpeedFace). La configuración es la misma para todos los modelos compatibles.

---

*¿Listo para recibir datos de asistencia en tiempo real en tu app en la nube? Comienza tu prueba gratuita — primer dispositivo gratis, configuración en menos de 15 minutos.*

Configurar Webhooks Biométricos Sin IP Fija

Introduction

Cómo Funcionan los Webhooks Biométricos

Paso 1: Crear Tu Endpoint Webhook

Paso 2: Registrar Tu Webhook con PunchConnect

Paso 3: Configurar Tu Dispositivo

Paso 4: Verificar Firmas de Webhook

Paso 5: Manejar Reintentos e Idempotencia

Checklist de Producción

Guías Relacionadas

Preguntas Frecuentes

¿Necesito una IP fija para recibir webhooks?

¿Qué pasa si mi servidor está caído cuando ocurre un fichaje?

¿Puedo recibir webhooks en una función serverless?

¿Cómo depuro las entregas webhook fallidas?

¿Funciona con los relojes checadores más comunes en Latinoamérica?

Artículos relacionados

Conectar ZKTeco a Odoo: Integración Cloud vía API REST (Sin VPN ni Software Local)

Integración Webhook ZKTeco: Pipelines de Asistencia en Tiempo Real con API REST

Integración API de Lector de Huellas: Guía para Desarrolladores sobre Biometría Cloud