Webhooks vs. polling: cómo elegir

Webhooks y polling resuelven una necesidad parecida: enterarse de cambios ocurridos en otro sistema. Un webhook envía una solicitud al consumidor cuando hay una novedad; el polling hace que el consumidor consulte periódicamente una API. Ninguno es superior en todos los casos. La elección depende de la urgencia, volumen, capacidad operativa y contrato disponible.

Antes de diseñar, lee la documentación del proveedor. Cada proveedor define su contrato: recursos consultables, tipos de evento, paginación, límites de uso, autenticación, códigos HTTP, reintentos, conservación del historial y garantías de orden. Una integración no debería inferir estas reglas a partir de otro servicio ni de un ejemplo genérico.

Cómo funciona cada patrón

En un webhook, el consumidor publica un endpoint accesible. El proveedor realiza una solicitud cuando ocurre un evento. El receptor valida la entrega, responde con rapidez y procesa el trabajo de forma controlada. La latencia suele ser baja porque no espera al siguiente intervalo de consulta.

En polling, el consumidor ejecuta una tarea programada: consulta elementos creados o modificados desde un cursor conocido, procesa la página y persiste el nuevo cursor. El consumidor controla el ritmo y no necesita exponer un endpoint entrante, aunque sí debe administrar intervalos, paginación y cuotas.

HTTP aporta la base de ambos modelos. RFC 9110 define la semántica de métodos, estados y campos; no define el contrato comercial de una API particular.

Comparación práctica

Criterio	Webhooks	Polling
Latencia	Habitualmente baja	Depende del intervalo
Tráfico sin cambios	Poco o ninguno	Puede generar consultas vacías
Exposición de red	Requiere endpoint receptor	Solo conexiones salientes
Control del ritmo	Compartido con el emisor	Principalmente del consumidor
Recuperación	Reintentos o reenvío según proveedor	Reconsulta desde cursor
Complejidad principal	Validación, deduplicación y recepción	Cursores, paginación y cuotas
Picos	Llegan cuando ocurren eventos	Pueden suavizarse por lotes

La tabla resume tendencias, no garantías. Un webhook puede demorarse y un polling frecuente puede ser rápido. También puede existir streaming, colas administradas o sincronización por archivos; no fuerces la decisión a solo dos opciones si el proveedor ofrece otro mecanismo oficial.

Cuándo suele convenir un webhook

Un webhook resulta apropiado cuando el cambio debe activar pronto una acción, los eventos son esporádicos o consultar constantemente produciría mucho tráfico vacío. Ejemplos genéricos incluyen iniciar una revisión al crearse un documento, actualizar una interfaz o colocar una tarea en una cola.

El equipo debe poder operar un endpoint público: certificados válidos, despliegues sin interrupciones innecesarias, límites de cuerpo, observabilidad y respuesta a incidentes. Además, la lógica debe admitir reintentos y concurrencia. Una respuesta exitosa solo confirma lo definido por el contrato; no prueba que todas las acciones posteriores terminaron.

Si el receptor se vuelve lento o devuelve errores, consulta qué hacer cuando un endpoint webhook no responde.

Cuándo suele convenir polling

Polling puede ser mejor cuando la API no ofrece webhooks, la actualización tolera demora, el volumen es predecible o la organización no puede exponer una ruta entrante. También facilita rehacer una ventana histórica si la API conserva registros consultables.

El intervalo exige equilibrio. Consultar cada segundo puede desperdiciar cuota; hacerlo una vez al día puede retrasar operaciones. Estima la demora aceptable, número de cuentas, páginas esperadas y límites del proveedor. Añade dispersión aleatoria para que muchas tareas no despierten exactamente al mismo tiempo.

Un buen polling no pregunta siempre “todo”. Usa el cursor oficial, fecha de modificación o token de página documentado. Si el proveedor no garantiza estabilidad para un filtro temporal, una fecha local no reemplaza un cursor.

Ejemplo de polling incremental en PHP

Este ejemplo hipotético consulta una API genérica y conserva un cursor solo después de procesar correctamente la página. El token sale del entorno. Ajusta URL, encabezados, paginación y validación al contrato real.

<?php

$apiToken = getenv('PROVIDER_API_TOKEN');
$cursorFile = __DIR__ . '/polling-cursor.txt';

if ($apiToken === false) {
    throw new RuntimeException('Falta PROVIDER_API_TOKEN');
}

$cursor = is_file($cursorFile) ? trim(file_get_contents($cursorFile)) : '';
$query = $cursor === '' ? '' : '?cursor=' . rawurlencode($cursor);

$handle = curl_init('https://api.example.test/v1/events' . $query);
curl_setopt_array($handle, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Accept: application/json',
        'Authorization: Bearer ' . $apiToken,
    ],
    CURLOPT_TIMEOUT => 15,
]);

$body = curl_exec($handle);
$status = curl_getinfo($handle, CURLINFO_RESPONSE_CODE);

if ($body === false || $status !== 200) {
    throw new RuntimeException('La consulta no pudo completarse');
}

$page = json_decode($body, true, flags: JSON_THROW_ON_ERROR);
if (
    !is_array($page) ||
    !isset($page['items'], $page['nextCursor']) ||
    !is_array($page['items']) ||
    !is_string($page['nextCursor'])
) {
    throw new RuntimeException('La respuesta no cumple el contrato esperado');
}

foreach ($page['items'] as $event) {
    processEventIdempotently($event['id'], $event);
}

if (file_put_contents($cursorFile, $page['nextCursor'], LOCK_EX) === false) {
    throw new RuntimeException('No se pudo guardar el cursor');
}

En una aplicación real, el cursor suele guardarse en una base de datos con una transacción adecuada, no en un archivo local que varias instancias podrían sobrescribir. processEventIdempotently representa una función del consumidor; su implementación debe evitar efectos duplicados. La documentación oficial de PHP describe las opciones y constantes de cURL utilizadas para configurar la solicitud.

El enfoque híbrido suele mejorar la recuperación

Una combinación frecuente usa webhooks para baja latencia y polling para reconciliación. El webhook coloca el evento en procesamiento; una tarea periódica consulta cambios desde el último cursor confirmado y recupera los que no llegaron o quedaron incompletos.

El modelo híbrido no debe crear dos caminos de negocio independientes. Ambos mecanismos deberían alimentar el mismo consumidor idempotente y usar la identidad lógica definida por el proveedor. De lo contrario, el webhook puede actualizar un pedido mientras el polling crea otro efecto por el mismo evento.

La guía sobre consumidores seguros de eventos desarrolla deduplicación, transacciones y estados recuperables. El objetivo del barrido periódico no es desconfiar de una tecnología, sino reducir el impacto de fallos parciales cuando la API permite reconstruir el historial.

Maneja paginación y ventanas sin perder datos

Una consulta incremental puede omitir cambios si avanza el cursor antes de completar la página. También puede repetirlos si el proceso cae después de aplicar efectos, pero antes de guardar el cursor. Por eso, procesa de forma idempotente y confirma el avance al final de una unidad durable.

Con filtros por tiempo, considera relojes desalineados, actualizaciones tardías y elementos modificados mientras recorres páginas. Una ventana solapada puede reducir omisiones, a costa de recibir duplicados que el consumidor debe reconocer. No inventes una tolerancia universal: documenta la estrategia según las garantías de la API.

Considera costos y límites

El costo no es solo infraestructura. Incluye tiempo de guardia, investigación, cuotas, almacenamiento de eventos y complejidad de pruebas. Un webhook con poco tráfico puede ser eficiente, pero requiere capacidad de recepción continua. El polling es conceptualmente directo, aunque miles de cuentas consultadas con frecuencia pueden multiplicar solicitudes vacías.

Respeta respuestas de limitación y el contrato de reintento. MDN explica el código 429 Too Many Requests, pero cada API determina cómo comunica sus cuotas y cuándo restablece capacidad. Añade límites locales para no producir una tormenta durante la recuperación.

Seguridad y privacidad cambian, no desaparecen

Webhooks requieren proteger una superficie entrante y validar cada solicitud de acuerdo con el proveedor. Polling requiere proteger credenciales salientes y limitar su alcance. Ambos necesitan rotación de credenciales, registros sin secretos, validación de datos y permisos mínimos.

No hay seguridad absoluta por elegir un patrón. Polling no es automáticamente seguro por ser saliente, y un webhook no es confiable solo porque use HTTPS. El diseño debe considerar amenazas, datos tratados y capacidad de detección.

Una decisión en cinco preguntas

Antes de elegir, responde:

1. ¿Cuál es la demora máxima aceptable?
2. ¿La fuente ofrece historial consultable y cursores confiables?
3. ¿Qué volumen y patrón de picos se esperan?
4. ¿El equipo puede operar un endpoint receptor disponible?
5. ¿Cómo se recuperarán eventos ausentes, repetidos o fuera de orden?

Si necesitas reacción rápida y existe un contrato de webhook maduro, comienza con recepción asíncrona e idempotente. Si toleras demora y la API ofrece consulta incremental sólida, polling puede ser suficiente. Si el proceso es crítico y ambos mecanismos están disponibles, combínalos alrededor de un único consumidor y una fuente clara de estado.

La decisión correcta no es la más moderna, sino la que permite detectar, procesar y reconstruir cambios bajo las condiciones reales del sistema. Conserva métricas, prueba recuperaciones y revisa el diseño cuando cambien el volumen o el contrato del proveedor.