Guía de Integración de Webhooks - LobbyFix

Previo

¿Qué son los Webhooks?

Requisitos Previos

Implementación

Paso 1: Configurar tu Webhook

Paso 2: ¿Qué información Recibes?

Paso 3: Monitorear tus Webhooks

Administración

Activar/Desactivar Webhooks

Tipos de Eventos

Apoyo

Errores Frecuentes

Integraciones Populares

Ejemplos de Código

Preguntas Frecuentes

¿Qué son los Webhooks?

Los webhooks te permiten recibir notificaciones automáticas en tiempo real cuando los visitantes entran o salen de tu ubicación. Es como tener un asistente que te avisa instantáneamente cada vez que algo importante sucede en tu recepción.

Casos de uso comunes:

• 🚪 Abrir puertas automáticamente cuando un visitante es aprobado
• 💬 Enviar notificaciones a Slack cuando llega un visitante VIP
• 📊 Registrar visitas en tu sistema interno de reportes
• 🔔 Enviar alertas personalizadas a tu equipo
• 🎫 Generar tickets o códigos de acceso automáticamente

Requisitos Previos

Antes de configurar tus webhooks, necesitas:

1. ✅ Tener una cuenta activa en LobbyFix con permisos de administrador
2. ✅ El módulo de Integraciones habilitado en tu ubicación (contacta a soporte si no lo ves)
3. ✅ Una URL pública HTTPS donde tu sistema pueda recibir las notificaciones

• Puede ser tu propio servidor
• O un servicio como Zapier, Make.com, o n8n

💡 ¿No tienes un servidor? Puedes usar herramientas como webhook.site para probar, o servicios de automatización como Zapier que te dan URLs de webhook listas para usar.

Paso 1: Configurar tu Webhook

Desde la Plataforma Web

1. Inicia sesión en tu cuenta de LobbyFix
2. Ve a Cuenta (esquina superior derecha) y selecciona la pestaña Integraciones
3. Haz clic en el botón azul "+ Agregar"
4. Completa el formulario:

Nombre

Un nombre descriptivo para identificar esta integración

Ejemplo: Notificaciones de Slack, Sistema de Control de Acceso, CRM Interno

Webhook URL

La dirección HTTPS donde quieres recibir las notificaciones

Ejemplo: https://tu-servidor.com/webhooks/lobbyfix

> ⚠️ Importante: La URL debe comenzar con https:// (no http://)

Eventos a enviar

Selecciona qué eventos quieres recibir:

• ☑️ Visitante entró (Check-in) - Se activa cuando un visitante ingresa físicamente
• ☑️ Visitante salió (Check-out) - Se activa cuando un visitante sale de la ubicación

5. Haz clic en "Crear Integración"

Probar tu Webhook

Después de crear el webhook:

1. Busca tu webhook en la lista de integraciones
2. Haz clic en "Test Webhook"
3. Si todo está bien, verás un mensaje verde: "✓ Éxito (XXXms)"
4. Si hay un error, revisa que tu URL sea correcta y esté accesible

Paso 2: ¿Qué Información Recibes?

Cuando ocurre un evento, LobbyFix envía un mensaje JSON a tu URL con toda la información del visitante.

Ejemplo de Notificación de Entrada

{
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "event_type": "visitor.checked_in",
  "timestamp": "2025-01-14T18:30:45.000Z",
  "data": {
    "checkin": {
      "id": 11761,
      "status": "INSIDE_LOCATION",
      "motive": "MEETING",
      "host": "Juan Pérez",
      "photo": "https://regiztra-s3.amazonaws.com/...",
      "created_at": "2025-01-14T18:30:45.000Z",
      "checked_in_at": "2025-01-14T18:30:45.000Z",
      "approval_method": "auto"
    },
    "visitor": {
      "id": 456,
      "name": "María García",
      "company_name": "Acme Corp",
      "phone": "+52 55 1234 5678"
    },
    "location": {
      "id": 42
    }
  }
}

Datos que Recibes

Paso 3: Monitorear tus Webhooks

Ver el Historial de Entregas

1. Ve a Cuenta > Integraciones
2. Busca tu webhook y haz clic en "Ver Logs"
3. Verás una lista de todos los eventos enviados:

• Estado verde (200 OK): La notificación se entregó correctamente ✅
• Estado rojo: Hubo un problema con la entrega ❌
• Latencia: Cuánto tardó tu servidor en responder
• Fecha: Cuándo se envió la notificación

4. Haz clic en "Ver" para ver los detalles completos:

• REQUEST: Lo que LobbyFix envió a tu servidor
• RESPONSE: Lo que tu servidor respondió

Indicadores de Estado

En la lista de integraciones verás:

• ACTIVO (verde): El webhook está funcionando
• DESHABILITADO (rojo): El webhook está pausado
• Último uso: Hace cuánto tiempo se usó

Activar/Desactivar Webhooks

Puedes pausar temporalmente un webhook sin eliminarlo:

1. Ve a Cuenta > Integraciones
2. Usa el interruptor (toggle) junto al nombre del webhook
3. Verde = Activo | Gris = Desactivado

Esto es útil cuando:

• Estás haciendo mantenimiento a tu servidor
• Quieres probar cambios sin recibir notificaciones
• Necesitas pausar temporalmente la integración

Editar o Eliminar Webhooks

Editar un Webhook

1. Ve a Cuenta > Integraciones
2. Haz clic en el ícono de lápiz ✏️ junto al webhook
3. Modifica los campos que necesites:

• Cambiar el nombre
• Actualizar la URL
• Agregar o quitar eventos

4. Haz clic en "Guardar Cambios"

Eliminar un Webhook

1. Ve a Cuenta > Integraciones
2. Haz clic en el ícono de papelera 🗑️ junto al webhook
3. Confirma la eliminación

⚠️ Nota: Esta acción no se puede deshacer. Si eliminas un webhook por error, tendrás que crearlo nuevamente.

Tipos de Eventos

🟢 Visitante Entró (visitor.checked_in)

Se activa cuando:

• Un visitante pasa por la recepción y se registra su entrada física
• El estatus del check-in cambia a "INSIDE_LOCATION" (Dentro de la ubicación)

NO se activa cuando:

• Un visitante está en la lista de espera
• Un visitante es aprobado pero aún no entra físicamente
• Un visitante es rechazado

Casos de uso:

• Abrir torniquetes o puertas automáticamente
• Notificar al anfitrión que su visitante ya llegó
• Registrar la hora exacta de entrada

🔴 Visitante Salió (visitor.checked_out)

Se activa cuando:

• Un visitante registra su salida en el sistema
• El sistema detecta una salida automática (si está configurado)

Casos de uso:

• Cerrar permisos de acceso temporales
• Calcular tiempo de permanencia
• Enviar encuestas de satisfacción al salir

Configuración Avanzada: Prioridades

Al crear o editar un webhook, puedes configurar la prioridad de entrega:

🟦 NORMAL (Recomendado)

• Tiempo de espera: 10 segundos
• Reintentos: Hasta 6 intentos si falla
• Entrega: En cola (no bloquea el proceso de check-in)

Usa NORMAL para:

• Notificaciones a Slack, Microsoft Teams, etc.
• Integraciones con CRMs o sistemas de reportes
• Cualquier caso donde unos segundos de retraso no sean críticos

⚡ HIGH (Alta Prioridad)

• Tiempo de espera: 5 segundos
• Reintentos: Hasta 3 intentos rápidos
• Entrega: Inmediata (puede afectar el tiempo de check-in)

Usa HIGH para:

• Sistemas de control de acceso físico (puertas, torniquetes)
• Validaciones en tiempo real que deben completarse antes de permitir el acceso
• Integraciones críticas que requieren respuesta inmediata

⚠️ Advertencia: Si tu servidor con prioridad HIGH tarda más de 5 segundos en responder, el proceso de check-in se retrasará. Usa esta opción solo si realmente la necesitas.

¿Por Qué Fallan los Webhooks?

Problema 1: Error 403 / 404 / 500

Causa: Tu servidor rechazó la solicitud o no está disponible

Solución:

1. Verifica que la URL sea correcta (sin espacios ni caracteres extraños)
2. Prueba la URL manualmente desde tu navegador
3. Revisa los logs de tu servidor para ver qué está fallando
4. Asegúrate de que tu aplicación esté corriendo

Problema 2: Timeout (Sin respuesta)

Causa: Tu servidor tarda demasiado en responder

Solución:

1. Tu servidor debe responder en menos de 10 segundos (5 segundos si es HIGH)
2. No hagas operaciones pesadas antes de responder "200 OK"
3. Procesa la información en segundo plano (después de responder)

Problema 3: Certificado SSL Inválido

Causa: Tu URL usa HTTPS pero el certificado no es válido

Solución:

1. Usa un certificado SSL válido (Let's Encrypt es gratis)
2. No uses certificados auto-firmados
3. Verifica que tu dominio tenga HTTPS correctamente configurado

Problema 4: No Recibo Notificaciones

Posibles causas:

✓ Webhook desactivado

→ Revisa que el toggle esté en verde (ACTIVO)

✓ Eventos no seleccionados

→ Edita el webhook y asegúrate de tener al menos un evento marcado

✓ Módulo de Integraciones no habilitado

→ Contacta a soporte para activar este módulo en tu cuenta

✓ URL incorrecta

→ Verifica que la URL sea accesible desde internet (no localhost)

✓ Firewall o bloqueo de IP

→ Asegúrate de que tu servidor permita conexiones desde AWS

Webhook Deshabilitado Automáticamente

Si tu webhook falla 50 veces seguidas, LobbyFix lo deshabilitará automáticamente para proteger ambos sistemas.

¿Cómo me entero?

1. Recibirás un email de notificación explicando que el webhook se deshabilitó
2. En la plataforma verás el estado "DESHABILITADO" en rojo
3. Verás el motivo: "Deshabilitado automáticamente por el administrador"

¿Qué hago?

1. Identifica el problema:

• Ve a Ver Logs y revisa los últimos errores
• Identifica el patrón: ¿timeout? ¿error 500? ¿URL incorrecta?

2. Corrige el problema:

• Arregla lo que esté fallando en tu servidor
• Si cambió la URL, actualiza el webhook

3. Prueba manualmente:

• Usa el botón "Test Webhook" para verificar que funciona

4. Reactiva el webhook:

• Usa el toggle para cambiar de DESHABILITADO a ACTIVO
• Monitorea los primeros eventos para confirmar que ya funciona

Integraciones Populares

Slack

Recibe notificaciones en tu canal de Slack cuando llegan visitantes.

Pasos:

1. En Slack, crea un Incoming Webhook
2. Copia la URL que te da Slack (ej: https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXX)
3. Usa un servicio intermedio como Zapier o Make.com para transformar el payload de LobbyFix al formato de Slack

Zapier

Conecta LobbyFix con miles de aplicaciones sin código.

Pasos:

1. Crea un nuevo Zap en Zapier
2. Como trigger, selecciona Webhooks by Zapier
3. Copia la URL del webhook que te da Zapier
4. Pégala en LobbyFix como tu Webhook URL
5. Configura las acciones que quieres realizar (enviar email, crear ticket, etc.)

Make.com (anteriormente Integromat)

Similar a Zapier, conecta LobbyFix con otras aplicaciones.

Pasos:

1. Crea un nuevo Scenario en Make.com
2. Agrega un módulo Webhooks > Custom webhook
3. Copia la URL del webhook
4. Pégala en LobbyFix
5. Configura los módulos para procesar los datos

n8n (Open Source)

Si prefieres alojar tu propia solución de automatización.

Pasos:

1. Instala n8n en tu servidor
2. Crea un nuevo workflow con un nodo Webhook
3. Configura el nodo para recibir POST requests
4. Copia la URL del webhook
5. Úsala en LobbyFix

Ejemplos de Código

Recibir Webhooks con Node.js

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

// Middleware para parsear JSON
app.use(express.json());

// Endpoint para recibir webhooks de LobbyFix
app.post('/webhooks/lobbyfix', (req, res) => {
  // Obtener los datos del visitante
  const { event_type, data } = req.body;
  const { visitor, checkin } = data;

  console.log(`Evento: ${event_type}`);
  console.log(`Visitante: ${visitor.name}`);
  console.log(`Empresa: ${visitor.company_name}`);
  console.log(`Anfitrión: ${checkin.host}`);

  // Responder rápidamente con 200 OK
  res.status(200).json({ received: true });

  // Hacer el procesamiento después de responder
  processWebhook(event_type, data);
});

function processWebhook(eventType, data) {
  if (eventType === 'visitor.checked_in') {
    // Lógica cuando entra un visitante
    console.log('Visitante ha entrado!');
    // Aquí puedes: abrir puertas, enviar notificación, etc.
  } else if (eventType === 'visitor.checked_out') {
    // Lógica cuando sale un visitante
    console.log('Visitante ha salido!');
    // Aquí puedes: cerrar accesos, calcular tiempo, etc.
  }
}

app.listen(3000, () => {
  console.log('Servidor escuchando en puerto 3000');
});

Recibir Webhooks con PHP

<?php
// Obtener el payload JSON
$payload = file_get_contents('php://input');
$data = json_decode($payload, true);

// Validar que sea un request válido
if (!$data || !isset($data['event_type'])) {
    http_response_code(400);
    echo json_encode(['error' => 'Invalid payload']);
    exit;
}

// Extraer información
$eventType = $data['event_type'];
$visitor = $data['data']['visitor'];
$checkin = $data['data']['checkin'];

// Log para debugging
error_log("Webhook recibido: $eventType");
error_log("Visitante: {$visitor['name']}");

// Responder rápidamente con 200 OK
http_response_code(200);
echo json_encode(['received' => true]);

// Procesar el webhook después de responder
if ($eventType === 'visitor.checked_in') {
    // Visitante entró
    processCheckin($visitor, $checkin);
} elseif ($eventType === 'visitor.checked_out') {
    // Visitante salió
    processCheckout($visitor, $checkin);
}

function processCheckin($visitor, $checkin) {
    // Tu lógica aquí
    // Ejemplo: Insertar en base de datos
    $pdo = new PDO('mysql:host=localhost;dbname=midb', 'user', 'pass');
    $stmt = $pdo->prepare("INSERT INTO visitas (nombre, empresa, hora_entrada) VALUES (?, ?, ?)");
    $stmt->execute([
        $visitor['name'],
        $visitor['company_name'],
        $checkin['checked_in_at']
    ]);
}

function processCheckout($visitor, $checkin) {
    // Tu lógica aquí
}
?>

Recibir Webhooks con Python (Flask)

from flask import Flask, request, jsonify
from datetime import datetime

app = Flask(__name__)

@app.route('/webhooks/lobbyfix', methods=['POST'])
def webhook():
    # Obtener el payload
    payload = request.get_json()

    if not payload or 'event_type' not in payload:
        return jsonify({'error': 'Invalid payload'}), 400

    event_type = payload['event_type']
    visitor = payload['data']['visitor']
    checkin = payload['data']['checkin']

    # Log
    print(f"Evento: {event_type}")
    print(f"Visitante: {visitor['name']}")
    print(f"Empresa: {visitor['company_name']}")

    # Responder rápido con 200 OK
    response = jsonify({'received': True})

    # Procesar después de responder
    if event_type == 'visitor.checked_in':
        process_checkin(visitor, checkin)
    elif event_type == 'visitor.checked_out':
        process_checkout(visitor, checkin)

    return response, 200

def process_checkin(visitor, checkin):
    # Tu lógica aquí
    print(f"Procesando entrada de {visitor['name']}")
    # Ejemplo: Guardar en base de datos, enviar email, etc.

def process_checkout(visitor, checkin):
    # Tu lógica aquí
    print(f"Procesando salida de {visitor['name']}")

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=3000)

Mejores Prácticas

✅ Recomendaciones

1. Responde rápido (< 3 segundos)

• Devuelve 200 OK inmediatamente
• Procesa los datos en segundo plano

2. Valida los datos

• Verifica que el JSON tenga los campos esperados
• Maneja casos donde falten datos opcionales

3. Registra todo (logs)

• Guarda cada webhook recibido
• Te ayudará a debuggear problemas

4. Evita duplicados

• Usa el campo event_id para detectar eventos repetidos
• Guarda los IDs procesados en una base de datos

5. Maneja errores

• Si algo falla en tu lógica, responde 200 OK de todas formas
• No dejes que errores internos bloqueen la recepción

6. Monitorea activamente

• Revisa periódicamente los logs en LobbyFix
• Configura alertas si hay muchos fallos

7. Usa HTTPS

• Nunca uses HTTP (no funcionará)
• Asegúrate de tener un certificado SSL válido

❌ Errores Comunes

1. No responder antes de procesar

• ❌ Procesar datos → Responder 200
• ✅ Responder 200 → Procesar datos

2. Usar HTTP en lugar de HTTPS

• ❌ http://mi-servidor.com/webhook
• ✅ https://mi-servidor.com/webhook

3. Hacer operaciones lentas antes de responder

• ❌ Enviar emails, consultar APIs externas, procesar imágenes
• ✅ Guardar en una cola y procesar después

4. No validar el payload

• ❌ Asumir que todos los campos siempre existen
• ✅ Verificar campos requeridos y usar valores por defecto

5. Ignorar los reintentos

• ❌ No detectar eventos duplicados
• ✅ Usar event_id para evitar procesar dos veces

Preguntas Frecuentes

¿Puedo tener múltiples webhooks?

Sí, puedes crear tantos webhooks como necesites. Por ejemplo:

• Un webhook para Slack
• Otro para tu sistema de control de acceso
• Otro para tu CRM

Cada uno puede tener eventos diferentes configurados.

¿Los webhooks cuestan extra?

Consulta con tu representante de ventas sobre las funcionalidades incluidas en tu plan.

¿Puedo probar sin un servidor propio?

Sí, usa webhook.site para ver los datos que se envían. También puedes usar Zapier o Make.com que te dan URLs listas.

¿Qué pasa si mi servidor está caído?

LobbyFix intentará enviar la notificación hasta 6 veces con retrasos crecientes. Si después de 6 intentos no responde, marcará el evento como fallido.

¿Se pueden recuperar eventos perdidos?

No se pueden reenviar automáticamente, pero puedes:

1. Ver el payload en los logs (Ver Logs > Ver > REQUEST)
2. Copiarlo y enviarlo manualmente a tu servidor
3. O consultarlo vía API usando el ID del check-in

¿Puedo filtrar eventos?

Actualmente puedes elegir entre:

• Solo entradas (visitor.checked_in)
• Solo salidas (visitor.checked_out)
• Ambos

No hay filtros más específicos (por ejemplo, solo visitantes VIP). Tendrás que filtrar en tu servidor.

¿La foto del visitante expira?

Sí, la URL de la foto es temporal (firmada con AWS S3). Si necesitas la foto:

1. Descárgala inmediatamente al recibir el webhook
2. Guárdala en tu propio almacenamiento
3. No almacenes solo la URL

¿Puedo usar localhost para pruebas?

No, la URL debe ser accesible desde internet. Para desarrollo local:

• Usa ngrok para exponer tu localhost
• O usa webhook.site para ver los payloads
• O despliega a un servidor de staging

Soporte

¿Necesitas ayuda?

📧 Email: soporte@lobbyfix.com

💬 Chat: Disponible en la plataforma (esquina inferior derecha)

📞 Teléfono: Consulta tu portal para el número de soporte

Al contactar soporte, incluye:

• Nombre del webhook o ID
• Captura de pantalla de los logs (si aplica)
• Descripción del problema
• URL del webhook (si es seguro compartirla)

Recursos Adicionales

• 🌐 webhook.site - Herramienta para probar webhooks
• 🔗 Zapier - Automatización sin código
• 🔗 Make.com - Alternativa a Zapier
• 🔧 ngrok - Exponer localhost para pruebas
• 📘 Postman - Herramienta para probar APIs

Última actualización: Enero 2026

Versión: 1.0

Esta documentación es para usuarios de LobbyFix. Para documentación técnica de API, contacta al equipo de desarrollo.

Actualizado el: 15/01/2026