Configura Webhooks para conectar WaclisCAL con tus sistemas internos y bases de datos

Aprende a configurar Webhooks en WaclisCAL para recibir notificaciones HTTP en tiempo real cada vez que un cliente crea, reprograma o cancela una reserva, permitiéndote sincronizar tus bases de datos, sistemas de facturación o aplicaciones internas de forma automática.

1. Qué permite hacer

Los Webhooks representan el mecanismo más eficiente y moderno para conectar aplicaciones web. En lugar de que tus servidores tengan que consultar periódicamente a WaclisCAL si hay citas nuevas (polling), los Webhooks envían de manera inmediata un paquete de datos en formato JSON mediante una petición HTTP POST hacia la URL de tu servidor en el milisegundo exacto en que ocurre el evento.

Al configurar Webhooks en WaclisCAL puedes:

• Recibir datos completos de la reserva: nombre, correo, teléfono, respuestas del formulario, fecha, hora y enlace de videollamada.
• Suscribirte a eventos específicos del ciclo de vida de la cita:

- BOOKING_CREATED: Cuando se confirma una nueva reserva.

- BOOKING_RESCHEDULED: Cuando el cliente o el anfitrión modifican el horario.

- BOOKING_CANCELLED: Cuando una cita es anulada o cancelada.

- BOOKING_REJECTED: Si una solicitud de aprobación manual es rechazada.

• Proteger la comunicación mediante un Secreto de Firma (Webhook Secret) criptográfico para garantizar la autenticidad de los datos.

2. Cuándo utilizarlo

Recomendamos utilizar Webhooks en proyectos donde:

• Posees un sistema de gestión propio: Tienes un ERP, CRM o software médico a medida y necesitas que las citas de WaclisCAL se reflejen instantáneamente en tu propia base de datos (PostgreSQL, MySQL, MongoDB, etc.).
• Emitir facturación electrónica: Deseas que al confirmarse un turno se genere automáticamente una orden de cobro o factura en tu sistema contable.
• Plataformas de automatización avanzadas: Conectar con herramientas como Make, n8n o servidores serverless (AWS Lambda, Google Cloud Functions).

3. Antes de comenzar

Antes de crear un webhook, asegúrate de:

1. Tener un endpoint receptor público accesible mediante protocolo seguro HTTPS (ejemplo: https://api.tuempresa.com/v1/wacliscal-webhook).
2. Contar con permisos de Administrador en tu cuenta de WaclisCAL.
3. Conocer los eventos a los que deseas suscribir tu aplicación.

4. Paso a paso

Paso 1: Accede a la sección de Webhooks en WaclisCAL

1. En la barra lateral principal de WaclisCAL, haz clic en Ajustes.
2. En el menú de opciones de configuración, dirígete al apartado Desarrollador y selecciona Webhooks (también accesible desde el menú de Módulos).
3. Haz clic en el botón superior Nuevo Webhook o Agregar.

Paso 2: Define la URL de tu servidor (Subscriber URL)

1. En el campo URL del Suscriptor, escribe la dirección completa del endpoint receptor de tu servidor.
2. Recuerda que la URL debe comenzar obligatoriamente con https://. Los endpoints con http:// no son aceptados por razones de seguridad de datos.

Paso 3: Configura el Secreto de Firma (Webhook Secret)

1. En el campo Secreto, puedes ingresar una clave alfanumérica segura generada por ti o presionar el botón de generación automática.
2. Guarda este secreto en las variables de entorno de tu servidor (WACLISCAL_WEBHOOK_SECRET).
3. WaclisCAL incluirá una firma criptográfica HMAC-SHA256 en la cabecera X-WaclisCAL-Signature de cada envío para que tu servidor compruebe que la petición proviene legítimamente de WaclisCAL y no de terceros.

Paso 4: Selecciona los eventos de suscripción

1. Marca las casillas de los eventos que tu sistema necesita procesar:

- Reserva creada (BOOKING_CREATED): Notifica reservas nuevas.

- Reserva reprogramada (BOOKING_RESCHEDULED): Notifica cambios de día u hora.

- Reserva cancelada (BOOKING_CANCELLED): Notifica la liberación de un turno.

1. Si deseas que el webhook aplique a todos tus servicios, mantén activada la opción Todos los Tipos de Evento. Si solo deseas monitorear un servicio puntual, selecciona el evento específico en el menú desplegable.

Paso 5: Guarda y prueba la entrega

1. Haz clic en el botón Guardar Webhook.
2. Verás tu nuevo webhook listado en la tabla de webhooks activos con un indicador verde.
3. Para verificar la conectividad, haz clic en los tres puntos (...) del webhook y selecciona Enviar prueba (Ping).
4. Tu servidor recibirá un payload de prueba con un código de respuesta HTTP 200 OK.

5. Ejemplo de estructura del Payload JSON

A continuación se muestra un ejemplo simplificado de la estructura de datos que tu servidor recibirá ante el evento BOOKING_CREATED:

{
"triggerEvent": "BOOKING_CREATED",
"createdAt": "2026-09-15T15:30:00.000Z",
"payload": {
"bookingId": 4589,
"title": "Asesoría Comercial Personalizada",
"description": "Reunión estratégica para evaluación de requerimientos.",
"startTime": "2026-09-18T14:00:00.000Z",
"endTime": "2026-09-18T14:45:00.000Z",
"status": "ACCEPTED",
"organizer": {
"name": "Alex García",
"email": "alex@tuempresa.com",
"timeZone": "America/Argentina/Buenos_Aires"
},
"attendees": [
{
"name": "Mariana López",
"email": "mariana.lopez@cliente.com",
"timeZone": "America/Argentina/Buenos_Aires"
}
],
"responses": {
"name": "Mariana López",
"email": "mariana.lopez@cliente.com",
"phone": "+5491155554321",
"motivo": "Consulta sobre planes corporativos"
},
"location": "https://meet.google.com/abc-defg-hij"
}
}

6. Qué verá la persona que reserva

El envío de Webhooks se produce de manera asíncrona en el servidor:

• No añade ningún tiempo de espera adicional para el cliente.
• El cliente finaliza su reserva de forma inmediata viendo su pantalla de confirmación habitual.

7. Qué sucede después

1. Recepción en tu servidor: Tu endpoint debe procesar los datos y responder rápidamente con un código de estado HTTP en el rango 2xx (típicamente 200 OK).
2. Reintentos automáticos: Si tu servidor responde con un error (código 5xx, 4xx) o no responde en 10 segundos por caída temporal de conectividad, WaclisCAL ejecuta una política de reintentos exponenciales para asegurar que ningún dato se pierda.
3. Historial de entregas: En la lista de webhooks puedes consultar la bitácora de ejecuciones con los códigos de respuesta devueltos por tu servidor.

8. Problemas frecuentes

El servidor no recibe las peticiones del webhook

• Causa: El endpoint receptor está protegido por un firewall que bloquea peticiones externas, o la URL no está disponible públicamente en Internet (por ejemplo: URLs locales tipo localhost o IPs privadas).
• Solución: Asegúrate de que el endpoint sea accesible públicamente con certificado SSL válido. Para pruebas en entornos de desarrollo local, utiliza túneles seguros como ngrok o cloudflared.

Error de validación de firma HMAC

• Causa: El secreto configurado en el código de tu servidor difiere del secreto ingresado en el panel de WaclisCAL, o el payload fue alterado antes de calcular el hash.
• Solución: Calcula la firma HMAC-SHA256 utilizando el cuerpo crudo de la petición (raw body en bytes) antes de convertirlo a objeto JSON y compara el resultado con el encabezado X-WaclisCAL-Signature.

WaclisCAL reporta reintentos o marca el webhook como fallido

• Causa: Tu servidor demora más de 10 segundos en responder porque realiza tareas pesadas (como generar PDFs o enviar correos lentos) en el mismo hilo de recepción.
• Solución: Devuelve inmediatamente un código 200 OK al recibir el webhook y delega el procesamiento pesado a una cola de tareas en segundo plano (como Redis, RabbitMQ o Celery).

9. Buenas prácticas

• Valida siempre la firma de seguridad: Nunca proceses un webhook que modifique bases de datos críticas sin verificar previamente que la firma HMAC coincida con tu secreto.
• Diseña endpoints idempotentes: En caso de que se reciba una notificación duplicada por un reintento de red, comprueba si el bookingId ya fue procesado para evitar crear registros dobles.
• Responde con rapidez: Mantén el endpoint ligero: valida la firma, guarda el payload en cola y responde 200 OK en menos de 500 milisegundos.

10. Artículos relacionados

• Integra WaclisCAL con tus propios sistemas mediante la API REST v1 oficial
• Conecta WaclisCAL con Make para automatizar tus procesos sin programar
• Genera y administra tokens de acceso seguros por Tipo de Evento