- 1. Definiciones Técnicas: ¿Qué es una API y qué es un Webhook?
- API REST: El modelo Request-Response (Pull)
- Webhook: El modelo vent-Driven (Push / Inverted API)
- 2. Webhook vs. API REST: Tabla comparativa de diferencias técnicas
- 3. Webhook vs. API: ¿Cuándo utilizar cada enfoque?
- 4. Buenas prácticas para desarrolladores al trabajar con Webhooks
- 5. Conclusión: ¿Webhook o API? La importancia de combinar ambos patrones
Imagina que pides una pizza y llamas a la pizzería cada 30 segundos para saber si ya salió del horno versus pedirles que te envíen un SMS al momento en que el repartidor cruce la puerta. Esa es la diferencia fundamental entre hacer llamadas a una API y recibir un Webhook.
Aunque a menudo se comparan como alternativas excluyentes, en la arquitectura de software moderna las API REST y los Webhooks son las dos caras de una misma moneda event-driven.
En la mensajería empresarial (SMS, WhatsApp, RCS), la API se encarga de ejecutar acciones (enviar mensajes), mientras que el Webhook se encarga de escuchar eventos en tiempo real (notificaciones de entrega, respuestas entrantes) sin saturar tus servidores.
1. Definiciones Técnicas: ¿Qué es una API y qué es un Webhook?
API REST: El modelo Request-Response (Pull)
Una API (Interfaz de Programación de Aplicaciones) REST es un conjunto de reglas y protocolos que permite a un cliente solicitar datos o ejecutar acciones en un servidor remoto mediante el protocolo HTTP.
El patrón de comunicación de una API REST es sincrónico y se basa en el principio de consulta (polling o request-driven): el cliente toma la iniciativa.
- Mecanismo: Basado en cliente-servidor sincrónico. El cliente inicia una solicitud HTTP (GET, POST, PUT, DELETE) y espera la respuesta del servidor con un payload JSON/XML.
- Patrón de comunicación: Polling / Request-Driven.
- Casos de uso típicos:
- Envío síncrono de un mensaje transactional (ej. un código OTP de doble factor).
- Consulta puntal del estado de un lote o saldo de la cuenta.
El problema del Polling
Cuando una aplicación necesita saber si un recurso ha cambiado (por ejemplo, si un pago ha sido aprobado o si un mensaje ha sido entregado), el enfoque clásico con API es hacer Polling: realizar peticiones HTTP periódicas (cada N segundos) preguntando al servidor si hay novedades.
Este enfoque genera dos inconvenientes principales:
- Ineficiencia de recursos: La inmensa mayoría de las peticiones responderán «sin cambios», consumiendo ancho de banda, ciclos de CPU y cuotas de API inútilmente.
- Latencia: La información no se procesa en el instante en que ocurre, sino en el siguiente intervalo de consulta.
Webhook: El modelo vent-Driven (Push / Inverted API)
Un Webhook (a menudo llamado «API invertida» o HTTP callback) es un mecanismo que permite a un servidor notificar automáticamente a otra aplicación cuando ocurre un evento concreto.
En lugar de que el cliente pregunte repetidamente si hay novedades, el servidor toma la iniciativa cuando el evento se produce.
- Mecanismo: Callback HTTP asíncrono. Cuando ocurre un evento en el servidor de mensajería, este realiza una petición HTTP POST hacia un endpoint público expuesto por tu aplicación.
- Patrón de comunicación: Publish/Subscribe / Event-Driven.
- Casos de uso típicos:
- Recepción de informes de entrega (Delivery Reports / DLR).
- Captura de SMS/WhatsApp entrantes para mensajería bidireccional (chattings, bots).
2. Webhook vs. API REST: Tabla comparativa de diferencias técnicas
| Criterio | API REST (Modelo Pull) | Webhook (Modelo Push) |
| Iniciador de la petición | El cliente (Tu aplicación) | Plataforma externa (Servidor Esendex) |
| Flujo de datos | Sincrónico / Bajo demanda. | Asíncrono / Guiado por eventos (Event-Driven). |
| Latencia | Alta o variable (depende de la frecuencia de consulta). | Casi nula (tiempo real). |
| Consumo de recursos | Alto si se utiliza polling constante. | Mínimo (solo consume cuando hay un evento). |
| Complejidad de arquitectura | Baja en el cliente, alta si se escala la frecuencia de peticiones. | Requiere exponer un endpoint público seguro e idempotente. |
| Manejo de errores | Gestionado en la respuesta HTTP inmediata de la llamada. | Requiere políticas de reintento (retries) y colas de procesamiento. |
3. Webhook vs. API: ¿Cuándo utilizar cada enfoque?
No existe una herramienta superior a la otra; ambas cumplen funciones distintas dentro de una arquitectura distribuida.
Utiliza una API REST cuando:
- Necesites ejecutar acciones bajo demanda: Crear un usuario, enviar un mensaje, actualizar un perfil o eliminar un recurso.
- Requieras lectura de datos puntuales: Consultar el catálogo de productos, verificar un saldo o solicitar un reporte histórico.
- El cliente controle el ritmo: Cuando las acciones son consecuencia directa de la interacción de un usuario en la interfaz.
Utiliza Webhooks cuando:
- Necesites reaccionar a eventos en tiempo real: Procesar notificaciones de pago en una pasarela, recibir cambios de estado en un envío o capturar mensajes entrantes.
- Quieras eliminar el polling: Para optimizar el tráfico de red y evitar sobrecargar los servidores con peticiones redundantes.
- Integres arquitecturas de microservicios asíncronas: Donde los componentes deben reaccionar a cambios de estado en subsistemas de terceros de forma desacoplada.
4. Buenas prácticas para desarrolladores al trabajar con Webhooks
- Respuestas rápidas (HTTP 200 OK): Acepta el webhook enviando un 200 OK inmediatamente antes de realizar procesamiento pesado. Si procesas la lógica en la misma petición HTTP, te arriesgas a superar el timeout y provocar reintentos innecesarios.
- Procesamiento asíncrono via queues: Recibe el payload en el webhook, colócalo en una cola de mensajes (RabbitMQ, AWS SQS, Redis) y procésalo con un worker en segundo plano.
- Garantizar la idempotencia: Es posible que recibas el mismo webhook más de una vez debido a reintentos por fallos de red. Utiliza el messageId o eventId como clave única en la base de datos para no duplicar acciones (como enviar un correo de confirmación dos veces).
- Seguridad y verificación: Valida el certificado SSL/TLS (HTTPS obligatorio en Esendex) y verifica las firmas de las cabeceras para asegurar que la petición proviene realmente de las IPs oficiales de Esendex.
5. Conclusión: ¿Webhook o API? La importancia de combinar ambos patrones
La dicotomía no es Webhook vs. API, sino Webhook con API.
Las API REST son la vía estándar para ordenar a un sistema que haga algo o para solicitar información. Los Webhooks son la vía eficiente para que un sistema te avise cuando algo ha sucedido. Al combinar ambos patrones, se logran arquitecturas de software modernas, eficientes y verdaderamente orientadas a eventos.
