Cuando una empresa empieza a conectar sus aplicaciones —centralita, CRM, ERP, Slack o Teams— casi siempre acaba en la misma encrucijada: ¿hago una integración a medida o uso webhooks? Y, antes de eso, la pregunta más básica de todas: ¿qué es exactamente un webhook?
Este artículo va al grano: una explicación técnica clara, cuándo conviene un webhook frente a una API REST, cinco escenarios reales que vemos a diario en pymes y medianas empresas, y cómo se activan los webhooks de Conexia Infinity sin tocar tu PBX.
¿Qué es un webhook y cómo funciona?
Un webhook es una notificación HTTP automática. Cada vez que pasa algo relevante en un sistema (una llamada entra, un cliente envía un SMS, una grabación se genera, una factura se cobra), ese sistema envía un POST a una URL que tú has configurado previamente. Llega un JSON con los datos del evento y tu aplicación reacciona al instante.
La diferencia con una API tradicional es conceptual: con la API, tu sistema pregunta ("dame las llamadas de la última hora"). Con webhooks, el sistema te avisa ("acaba de entrar una llamada con estos datos"). No hay polling, no hay retrasos.
Analogía rápida. Un webhook es como suscribirte a una newsletter por email: el remitente te avisa cuando hay algo nuevo. Una API es como entrar a la web cada cinco minutos a comprobar si hay novedades. Si esperas un evento poco frecuente pero importante (una llamada perdida, un cobro), suscribirte sale más a cuenta que estar mirando.
Webhook vs API REST: cuándo usar cada uno
Webhook y API no compiten, se complementan. La regla rápida: API para consultar y ejecutar bajo demanda, webhook para reaccionar a eventos. Esta tabla resume las diferencias prácticas:
| Aspecto | Webhook (push) | API REST (pull) |
|---|---|---|
| Dirección del flujo | El sistema avisa a tu app | Tu app pregunta al sistema |
| Latencia | Tiempo real (segundos) | Depende de la frecuencia de polling |
| Carga de red | Solo cuando hay evento | Constante, incluso sin novedades |
| Mejor para | Llamadas entrantes, SMS, cobros, alertas | Históricos, reportes, ejecución bajo demanda |
| Requiere | Endpoint público accesible por HTTPS | Cliente HTTP y token de autenticación |
En integraciones serias casi siempre conviven los dos: API para consultar el histórico y webhooks para reaccionar a lo que pasa ahora mismo.
5 ejemplos prácticos en empresa
Estos son patrones que vemos en producción con clientes de Conexia Infinity. Cada uno parte de un evento de la centralita y termina en una acción concreta en otra herramienta.
Notificar a Slack o Teams cuando entra una llamada VIP
Si entra una llamada de un número marcado como cliente Premium o si una cola supera el SLA acordado, el equipo recibe un mensaje al instante en el canal correspondiente con número, agente disponible y tiempo de espera. Cero llamadas perdidas por no estar mirando el panel.
Crear ticket en el CRM al recibir un SMS o WhatsApp
Cuando un cliente responde por SMS o por WhatsApp Business a una plantilla de Omnia, el webhook crea automáticamente un ticket en Zoho, HubSpot o Salesforce con el mensaje, el número y la conversación previa enlazada. El comercial entra a las 9 de la mañana y tiene la cola priorizada.
Sincronizar contactos al alta de un nuevo cliente
Al firmar un alta en el CRM, el webhook empuja el contacto a la centralita y a la agenda nacional. La próxima vez que ese número llame, aparece identificado en el softphone con nombre y empresa. Sin cargas masivas ni exportaciones manuales.
Disparar email tras un evento de facturación
Al cierre de mes, el evento de tarificación dispara un webhook que genera y envía la factura PDF al cliente con detalle de consumo, además de avisar al departamento financiero por email o Telegram si hay desviación frente al mes anterior.
Log a Google Sheets o data warehouse
Cada llamada finalizada se vuelca a una hoja de Google Sheets compartida (para reporting rápido) o a BigQuery / Snowflake (para BI serio): duración, agente, cola, resultado, coste. La dirección comercial ya no espera al informe mensual.
Cómo configurar webhooks en Conexia
En Conexia Infinity la activación es por panel, sin tocar tu PBX ni desplegar middleware. El equipo de canal valida la configuración antes de pasar a producción. Estos son los pasos básicos:
- Define el endpoint receptor. Necesitas una URL HTTPS pública accesible desde Internet. Puede ser tu backend, un servicio serverless (Cloud Functions, Lambda) o una herramienta de automatización como Make, n8n o Zapier.
- Solicita la activación al equipo de canal. Desde el panel o por soporte se habilita el módulo de webhooks y se obtiene la clave de firma HMAC con la que validarás los mensajes entrantes.
- Suscríbete solo a los eventos que necesitas. Llamada iniciada, contestada, finalizada, buzón de voz, interacción de cliente, tarificación, cola y agentes, marcador. No pidas todo: filtra desde el origen.
- Implementa el receptor. Tu endpoint debe responder
200 OKen menos de 5 segundos. Si tu lógica es lenta, recibe, encola y responde rápido; procesa después. - Verifica la firma HMAC-SHA256. Cada POST incluye una cabecera con la firma del payload. Compárala con la calculada localmente para asegurarte de que viene de Conexia y no de un tercero.
- Prueba en sandbox y pasa a producción. Lanza llamadas de prueba, revisa el panel de webhooks (histórico, latencia y tasa de éxito) y activa los eventos en producción cuando todo cuadre.
Sin desarrollo en tu PBX. Conexia Infinity expone los webhooks como capa de producto: tú solo defines URL y eventos. Si no tienes equipo de desarrollo, también funcionan perfectamente con Make, n8n o Zapier — recibes el evento como trigger y arrastras los pasos siguientes.
Seguridad y buenas prácticas
Un webhook es un endpoint expuesto a Internet. Hay tres mecanismos básicos que conviene aplicar siempre:
1. Firma HMAC-SHA256
Conexia firma cada payload con una clave compartida. En tu receptor, recalcula la firma sobre el cuerpo del POST y compárala con la cabecera X-Conexia-Signature. Si no coincide, descarta el mensaje. Esto evita que un tercero envíe payloads falsos a tu endpoint público.
2. Reintentos con backoff
Si tu endpoint devuelve un 5xx o no responde, Conexia reintenta el envío con backoff exponencial durante hasta 24 horas. Esto es bueno (no pierdes eventos) pero también peligroso: tu receptor debe ser idempotente. Si procesas dos veces el mismo evento, no puede crear dos tickets ni cobrar dos veces.
3. Idempotencia con identificadores únicos
Cada evento llega con un uid único. Guárdalo en tu base de datos al procesar. Si recibes el mismo uid dos veces (un reintento que llegó tarde), ignora la segunda. Es una línea de código que ahorra muchos dolores de cabeza.
Buenas prácticas adicionales. Usa siempre HTTPS (nunca HTTP plano), limita tu endpoint por IP si tu firewall lo permite, registra los payloads recibidos durante los primeros días para diagnosticar problemas y monitoriza la latencia desde el panel de Conexia: una caída a 0% de éxito es la primera señal de que algo se ha roto en tu lado.
Errores comunes y cómo evitarlos
Lo que vemos romper integraciones de webhooks en producción, por orden de frecuencia:
- Endpoint que tarda demasiado en responder. Si tu receptor procesa el evento síncronamente (ej. genera un PDF antes de devolver 200), el timeout dispara reintentos y duplicidades. Recibe, encola, responde — procesa después.
- No verificar la firma. Cualquiera con la URL puede enviar payloads. Validar la firma cuesta cinco líneas de código y blinda el endpoint.
- Falta de idempotencia. Sin control del
uid, los reintentos crean duplicados en CRM, tickets repetidos en helpdesk y entradas dobles en la hoja de cálculo. - Suscribirse a todos los eventos. Sobrecarga el receptor con tráfico que no usas y dificulta el debugging. Filtra desde el origen: solo los eventos que realmente disparan acciones.
- No monitorizar. Conexia expone un panel con histórico, latencia y tasa de éxito por endpoint. Si nadie lo mira, una caída se descubre tarde — cuando el cliente reclama que no recibió la factura.
- Cambios de URL sin coordinación. Mover el receptor a una nueva ruta sin actualizar la configuración en Conexia rompe la integración en silencio. Si vas a migrar, mantén ambos endpoints activos durante un tiempo de transición.
En resumen: los webhooks son la pieza más sencilla de toda la pila de integraciones, pero la que más fácil se subestima. Bien configurados, eliminan el polling, reducen latencia y abren un montón de automatizaciones que antes pedían un proyecto de varios meses. Mal configurados, generan duplicados, eventos perdidos y noches en vela.