Webhooks o consultas programadas: qué necesita la integración de tu empresa
Un webhook avisa cuando ocurre un cambio; una consulta programada pregunta cada cierto tiempo si hay novedades. La primera opción reduce espera y llamadas vacías, mientras que la segunda controla el ritmo y puede recuperar periodos completos. Ninguna garantiza por sí sola que CRM, ERP o tienda terminen de acuerdo. La decisión correcta empieza por el retraso tolerable y el coste de perder o duplicar un cambio.
Lo esencial, antes de empezar
- Usa eventos cuando el negocio debe reaccionar rápido y el proveedor ofrece una entrega que puedes autenticar, registrar y reintentar.
- Usa consultas programadas cuando se tolera retraso, no hay webhook fiable o necesitas recuperar cambios desde un punto conocido.
- Para datos críticos suele ser útil un diseño híbrido: webhook como señal rápida y consulta delta o conciliación como red de recuperación.
- La robustez depende de idempotencia, orden, checkpoint, reintentos, firma, alertas y prueba de eventos perdidos, no del nombre del patrón.
Decide con cuatro preguntas de negocio
Antes de hablar de tecnología, responde: ¿cuánto retraso se tolera?, ¿qué ocurre si falta un cambio?, ¿qué mecanismo ofrece realmente el proveedor? y ¿cómo se demostrará que ambos sistemas cuadran?
| Situación | Punto de partida | Por qué |
|---|---|---|
| Pago aprobado o pedido nuevo | Webhook más verificación | La reacción importa y el estado final debe confirmarse |
| Catálogo nocturno | Consulta incremental o lote | Minutos u horas de retraso son aceptables |
| CRM con cambios durante el día | Híbrido | Evento para rapidez y delta para completar huecos |
| Sistema sin callbacks | Polling o archivo soportado | No puedes exigir una capacidad que el origen no ofrece |
| Volumen bajo y proceso no crítico | La opción más simple operable | La complejidad en tiempo real puede no aportar valor |
La documentación de Microsoft Graph recomienda notificaciones de cambio frente a sondeo frecuente y combina notificaciones con consultas delta. Es un ejemplo del patrón híbrido: el aviso reduce latencia; el estado consultable permite recuperar o confirmar.
Webhook, polling y lote resuelven necesidades distintas
- 01
Webhook o push
El origen envía una notificación a un endpoint cuando ocurre un evento. Reduce consultas vacías, pero exige disponibilidad, autenticación, control de ráfagas y duplicados.
- 02
Polling incremental
El destino consulta desde un cursor, fecha o versión. Controla frecuencia y puede reanudar, pero introduce retraso y consume cuota aunque haya pocos cambios.
- 03
Lote
Se intercambia un conjunto cerrado en una ventana. Facilita conciliación y grandes volúmenes, aunque no sirve para reacciones inmediatas.
- 04
Híbrido
El webhook despierta el proceso y una consulta periódica compara el periodo para recuperar eventos ausentes, tardíos o fuera de orden.
Google explica que las notificaciones push de Calendar usan canales y un endpoint HTTPS para avisar de cambios. La notificación no sustituye necesariamente la lectura del recurso y el canal tiene ciclo de vida. El contrato concreto del proveedor manda sobre una definición genérica.
Si el sistema ni siquiera ofrece una API o callback, consulta las alternativas para integrar un programa sin API. Forzar polling contra una interfaz no documentada puede ser más frágil que un archivo soportado.
Escribe el contrato de cada flujo antes del transporte
| Campo | Pregunta que debe responder |
|---|---|
| Entidad y propietario | ¿Pedido, contacto, pago o stock? ¿Qué sistema manda? |
| Cambio | ¿Alta, actualización, borrado, transición o foto completa? |
| Frescura | ¿Segundos, minutos, horas o cierre diario? |
| Impacto | ¿Qué ocurre si llega tarde, dos veces, fuera de orden o no llega? |
| Mecanismo primario | ¿Webhook, delta, lote o archivo? |
| Checkpoint | ¿Desde qué cursor, ID o marca puede reanudarse? |
| Recuperación | ¿Cómo se consulta el estado y se concilian huecos? |
| Alerta y dueño | ¿Quién actúa y qué evidencia recibe? |
Una integración CRM–ERP puede usar varios patrones: cliente nuevo por evento, catálogo por lote y conciliación financiera programada. No impongas el mecanismo a toda la relación. Documenta también límites de cuota, paginación, retención de cambios y condiciones de borrado.
Un webhook necesita autenticidad, respuesta rápida e idempotencia
- Autenticar: verifica firma, secreto, certificado u otro mecanismo documentado; aplica protección contra replay cuando el proveedor la contemple.
- Persistir: registra ID, tipo, tiempo y payload mínimo antes del trabajo pesado; responde según el contrato del emisor.
- Desacoplar: procesa en cola o estado recuperable para absorber ráfagas y no depender de la latencia del ERP.
- Deduplicar: una restricción por ID de evento o clave estable evita repetir el efecto cuando el proveedor reintenta.
- Ordenar con cautela: usa versión o estado actual; no asumas que la red conserva orden.
- Observar: mide recepción, cola, proceso, error, antigüedad y último evento por integración.
Responder 2xx solo confirma recepción según el contrato; no demuestra que el pedido esté creado en el ERP. Conserva una referencia que permita consultar el resultado. Si el proceso cae después de actuar y antes de marcar éxito, la repetición debe recuperar el resultado anterior o reconciliar antes de escribir otra vez.
El polling necesita checkpoint y límites, no un bucle infinito
Consulta por `updated since`, cursor o ID cuando la API lo permita; pagina hasta cerrar el rango y avanza el checkpoint solo después de persistir el lote. Para evitar perder cambios con la misma marca temporal, usa solape controlado y deduplicación, o el mecanismo recomendado por el proveedor.
Las prácticas recomendadas de la API REST de GitHub aconsejan webhooks cuando sea posible y, para polling, un calendario fijo, peticiones condicionales, solo los datos necesarios y tratamiento de errores. Esas medidas reducen carga, pero siguen dependiendo del contrato de cada API.
| Problema | Control |
|---|---|
| Consulta solapada | Lock o lease por integración y ventana |
| Límite de API | Frecuencia acordada, paginación y respuesta a 429 |
| Página parcial | Cursor persistido y lote repetible |
| Cambio durante la lectura | Ventana estable, versión o segunda pasada según contrato |
| Borrados no visibles | Tombstones, endpoint específico o conciliación completa periódica |
| Sin novedades durante demasiado tiempo | Heartbeat y alerta de silencio, no asumir tranquilidad |
La reconciliación convierte velocidad en confianza
Una tarea de reconciliación toma un rango cerrado, consulta el sistema propietario y compara referencias, versiones o totales con el destino. No necesita repetir toda la integración cada minuto. Puede ejecutarse después de una incidencia, al cierre diario o con una frecuencia proporcional al impacto.
- 01
Duplicado
Repite un evento o incluye el mismo registro en dos páginas; debe conservarse un solo efecto.
- 02
Retrasado
Entrega una versión antigua después de una nueva; el estado no debe retroceder sin una regla explícita.
- 03
Perdido
Omite una notificación y demuestra que la consulta delta o conciliación recupera el cambio.
- 04
Caída del destino
Mantén el evento y reanuda con backoff sin bloquear la recepción de otros casos.
- 05
Resultado incierto
Corta la conexión tras enviar y consulta por referencia antes de repetir.
- 06
Secreto inválido
Rechaza sin procesar, alerta sin exponer credenciales y permite rotación controlada.
La guía de mantenimiento de automatizaciones en producción desarrolla reintentos, idempotencia, alertas y recuperación. Este artículo sitúa esos controles dentro de la elección push, pull o lote.
Ejemplo hipotético y ficha final de decisión
Ejemplo hipotético: una tienda envía nuevos pedidos al ERP mediante webhook porque preparación necesita reaccionar pronto. El receptor verifica firma, guarda ID y encola. Cada noche consulta pedidos modificados y compara identificadores, importes y estados; recupera cualquier hueco. El catálogo se importa por lote porque no requiere inmediatez. El ejemplo no describe una implementación o resultado de NAS.
- Retraso máximo y volumen, incluidos picos.
- Eventos, consultas delta, lotes y límites que documenta el proveedor.
- Sistema propietario, ID estable y regla para conflicto de versiones.
- Firma, permisos, exposición de red y datos mínimos.
- Idempotencia, retry, checkpoint y mecanismo de reconciliación.
- Pruebas de duplicado, pérdida, orden, caída y recuperación.
- Alertas, responsable, procedimiento manual y objetivo de mantenimiento.
Diseña para cambios y límites del proveedor
La elección entre webhook y consulta periódica no elimina el riesgo de una versión retirada. Mantén inventario, pruebas contractuales y plan de migración con la guía sobre cambios de versión en APIs. Calcula también ritmo medio, ráfagas y reintentos mediante la guía de límites y cuotas de API para no convertir la recuperación en otra sobrecarga.
Fuentes y referencias
Documentación oficial y referencias de mercado consultadas para verificar los puntos que cambian con el tiempo.
