Configuración de Webhooks sin IP Estática

El problema con las configuraciones tradicionales

La mayoría de los sistemas biométricos de asistencia requieren un servidor local funcionando las 24 horas con una dirección IP estática. El dispositivo se conecta a tu servidor vía TCP, y si tu servidor se cae o tu IP cambia, pierdes los datos de fichaje.

Esta arquitectura fue diseñada a principios de los 2000, cuando los servidores locales eran la norma. Pero hoy en día, la mayoría de los equipos ejecutan sus aplicaciones en la nube — en AWS, GCP, Azure o plataformas como Railway y Render.

PunchConnect invierte este modelo por completo. En lugar de que tu servidor escuche las conexiones de los dispositivos, PunchConnect actúa como intermediario. Tus dispositivos envían datos a PunchConnect, y PunchConnect los envía a tu aplicación mediante webhooks.

Cómo funcionan los webhooks de PunchConnect

Cuando un empleado registra su entrada o salida en un dispositivo biométrico, el dispositivo envía el evento al motor de protocolo de PunchConnect. PunchConnect procesa el evento, normaliza los datos e inmediatamente envía una solicitud HTTP POST a tu URL de callback configurada.

Tu URL de callback puede ser cualquier endpoint accesible públicamente — una función serverless en Vercel, una ruta Flask en Railway, un endpoint Express en Render, o incluso un webhook de Zapier.

PunchConnect incluye reintentos automáticos con backoff exponencial. Si tu servidor no está disponible temporalmente, los eventos se ponen en cola y se reintentan durante un máximo de 72 horas. No se pierde ningún dato.

Paso 1: Crear un endpoint para webhooks

Primero, crea un endpoint simple en tu servidor que acepte solicitudes POST. Aquí tienes un ejemplo usando Express.js:

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

  // Verify the webhook signature
  const signature = req.headers['x-punchconnect-signature'];
  if (!verifySignature(req.body, signature, WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Process the attendance event
  console.log(`${event}: ${employee_id} at ${timestamp}`);

  // Always respond with 200 to acknowledge receipt
  res.status(200).json({ received: true });
});

Paso 2: Registrar el webhook

Usa la API de PunchConnect para registrar la URL de tu webhook para el dispositivo:

from punchconnect import PunchConnect

client = PunchConnect(api_key="pc_live_your_api_key")

webhook = client.webhooks.create(
    device_id="dev_abc123",
    url="https://your-app.com/api/attendance",
    events=["punch_in", "punch_out"],
    secret="whsec_your_signing_secret"
)

print(f"Webhook active: {webhook.id}")

Paso 3: Probar la integración

PunchConnect proporciona un endpoint de prueba que simula un evento de fichaje. Úsalo para verificar que tu webhook funciona correctamente antes de conectar un dispositivo real.

También puedes ver los registros de entrega de webhooks en tu panel de control — cada solicitud, código de respuesta e intento de reintento queda registrado para depuración.

curl -X POST https://api.punchconnect.com/v1/webhooks/test \
  -H "Authorization: Bearer pc_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"webhook_id": "whk_abc123", "event": "punch_in"}'

Consideraciones de seguridad

Verifica siempre las firmas de los webhooks. PunchConnect firma cada payload de webhook usando HMAC-SHA256 con tu secreto de webhook. Esto garantiza que la solicitud proviene genuinamente de PunchConnect y no ha sido manipulada.

Usa HTTPS para tu URL de callback. PunchConnect no entregará webhooks a endpoints HTTP sin cifrar en modo de producción.

Implementa idempotencia. En casos excepcionales (timeouts de red), PunchConnect puede entregar el mismo evento dos veces. Usa el campo event_id para deduplicar.

Conclusión

Con los webhooks de PunchConnect, no necesitas una IP estática, un servidor local ni configuraciones de red complejas. Simplemente despliega tu aplicación en cualquier lugar, expone un endpoint y recibe datos de asistencia en tiempo real.

La configuración completa toma aproximadamente 15 minutos — desde la creación de tu cuenta hasta la recepción de tu primer evento de fichaje en vivo.