Skip to main content
InicioBlogGuíasCómo conciliar las actualizaciones de Webhook omitidas con el sondeo periódico de la API: una guía práctica de sincronización híbrida

Cómo conciliar las actualizaciones de Webhook omitidas con el sondeo periódico de la API: una guía práctica de sincronización híbrida

17TRACK

Usa webhooks para las actualizaciones inmediatas y consultas periódicas de la API para comprobar si el registro de envío local aún coincide con el registro del proveedor. El patrón fiable consiste en almacenar de forma duradera las entregas de webhooks, reconciliarlas con la API mediante identificadores de envío estables y aplicar ambas vías mediante la misma lógica de actualización idempotente. Las consultas pueden reparar cambios de estado perdidos, pero no pueden reconstruir eventos intermedios a menos que la API exponga realmente el historial de eventos.

Cómo reconciliar actualizaciones de webhooks perdidas con consultas periódicas de la API

Esta guía está dirigida a los ingenieros y equipos de operaciones responsables de mantener sincronizados un sistema de gestión de pedidos, una página de seguimiento o una vista de atención al cliente con los datos de los envíos. Su regla central es sencilla: trata un webhook como una señal para inspeccionar y procesar un cambio, no como una prueba de que todos los cambios anteriores hayan llegado.

Define qué significa «sincronizado» antes de elegir un intervalo

Una integración de envíos puede necesitar conservar dos cosas diferentes: el estado actual, como «en tránsito» o «entregado», y el historial de eventos que explica cómo se llegó a ese estado. La consulta de envíos de un proveedor puede devolver el estado más reciente, una lista de eventos de seguimiento o ambos. Estas estructuras de API ofrecen distintas garantías de recuperación.

Si la consulta solo devuelve una instantánea del estado actual, una consulta de reconciliación puede corregir el estado local después de un webhook perdido. No puede demostrar qué estados intermedios ocurrieron. Si la API devuelve eventos históricos con identificadores o marcas de tiempo estables, la consulta también puede recuperar entradas de la línea de tiempo que falten. Comprueba el esquema de respuesta real del proveedor antes de prometer cualquiera de estos resultados a los usuarios posteriores.

Anota los campos que tu aplicación debe reconciliar: identificador del envío, transportista o identificador de seguimiento, estado normalizado, estado del proveedor, hora del evento, hora de la última actualización del proveedor, datos de entrega y cualquier campo utilizado para activar mensajes a los clientes. Separa los campos cuya autoridad corresponde al proveedor de los campos gestionados localmente, como una nota interna del caso. Un proceso de reconciliación no debe sobrescribir datos exclusivamente locales simplemente porque estén ausentes en una respuesta de la API.

Construye una única ruta de procesamiento para los resultados de webhooks y consultas

Los controladores de webhooks y los procesos de consulta no deben implementar reglas contrapuestas para los cambios de estado. Ambos deben producir una observación normalizada y pasarla a una única función de reconciliación. Esa función valida la identidad, compara la observación con el envío almacenado, escribe una actualización segura y registra por qué realizó el cambio.

  1. Recibir y autenticar. Valida un webhook mediante el mecanismo documentado por el proveedor. Rechaza las solicitudes que no superen la validación, pero conserva suficiente información de diagnóstico no sensible para investigar los problemas de entrega.
  2. Persistir antes de confirmar. Coloca una entrega válida en un almacenamiento duradero o en una cola antes de devolver una respuesta correcta. Una respuesta HTTP correcta enviada antes de la persistencia crea una brecha que un reintento del proveedor podría no reparar.
  3. Normalizar. Mapea la carga útil del proveedor o la respuesta de la API a una estructura interna común, conservando los valores originales del proveedor para la investigación.
  4. Reconciliar. Usa una clave de envío estable y una regla de idempotencia para evitar entradas duplicadas en la línea de tiempo, notificaciones repetidas y escrituras innecesarias.
  5. Auditar el resultado. Registra si la observación cambió el envío, ya era conocida, era más antigua que el estado almacenado o requiere revisión manual.

Un ID de evento del proveedor resulta útil para la deduplicación si existe y es estable. Si no existe, puede ser necesaria una clave compuesta, pero sus componentes deben ajustarse al modelo de datos del proveedor. Dos escaneos legítimos pueden compartir un estado y una marca de tiempo, por lo que una clave basada únicamente en esos campos podría descartar un evento real. Conserva la carga útil sin procesar o una referencia a ella durante un periodo de retención definido para poder investigar las coincidencias ambiguas.

Diseña el ciclo de consultas en función del riesgo, no de un único temporizador global

Consultar todos los envíos conocidos con la misma frecuencia desperdicia solicitudes y puede ejercer presión sobre los límites de la API. Mantén un conjunto de envíos que puedan reconciliarse y selecciónalos según el riesgo operativo. Un envío recién registrado que aún no ha recibido su primera actualización, un envío con un fallo reciente en el procesamiento de un webhook y un envío cuyo estado no ha cambiado durante el flujo de trabajo esperado pueden requerir programaciones diferentes. Un envío completado puede necesitar solo una comprobación final limitada, dependiendo de si las correcciones tardías son relevantes para tu aplicación.

Elige un intervalo partiendo del tiempo máximo durante el cual tu negocio puede tolerar un estado local incorrecto. Ten en cuenta el retraso de la cola, el tiempo de solicitud, los reintentos y la capacidad de los procesos; el intervalo de consulta por sí solo no es el tiempo de recuperación. Añade variación aleatoria para evitar que muchos envíos venzan en el mismo instante. Si el proveedor documenta límites de solicitudes u ofrece una consulta por lotes, incorpora esas restricciones en lugar de suponer que un diseño que funciona en una prueba pequeña escalará sin cambios.

Mantén separado el registro del planificador del estado del proveedor. Campos como last_poll_attempt_at, last_successful_poll_at, next_poll_at y last_webhook_received_at responden a preguntas diferentes. En particular, una consulta intentada que agota el tiempo de espera no debe actualizar el indicador de consulta correcta.

Cuando la API admita solicitudes condicionales, un cursor de cambios documentado o un filtro de actualización desde una fecha determinada, evalúa si reduce las transferencias innecesarias sin ocultar registros. HTTP define el comportamiento de las solicitudes condicionales, incluida la respuesta 304 Not Modified, pero una integración debe utilizarlo solo si el endpoint correspondiente lo admite y sus semánticas están claras. Un cursor no es intercambiable con una marca de tiempo: confirma qué orden sigue, si está limitado a una cuenta o a un envío y cómo se comporta cuando los resultados están paginados.

Reconcilia sin revertir una actualización más reciente

La condición de carrera más común es sencilla: comienza una consulta, llega un webhook más reciente y la consulta devuelve una instantánea más antigua. Si el resultado de la consulta se escribe en último lugar sin comparación, el envío local retrocede. Evítalo comprobando la hora del evento o la versión del proveedor cuando sean fiables y haciendo que la comparación y la escritura sean atómicas para cada envío.

No supongas que la hora de llegada refleja el orden de los eventos. Un webhook entregado tarde puede describir un escaneo antiguo, mientras que una respuesta posterior de la API puede contener una corrección de un evento comunicado anteriormente. Define reglas separadas para la inserción en la línea de tiempo y la selección del estado actual. Por ejemplo, un escaneo antiguo puede pertenecer al historial sin reemplazar el estado actual. Una corrección del proveedor puede requerir modificar un evento almacenado en lugar de añadir otro. La regla correcta depende de los identificadores, las marcas de tiempo y las señales de revisión que proporcione el proveedor.

Si el proveedor no ofrece una versión o un campo de ordenación fiable, actúa con cautela. Compara el registro completo devuelto con el registro local, marca las contradicciones y evita tratar una etiqueta de estado como un esquema de ordenación universal. «Excepción», «en reparto» y «entregado» no siempre forman una secuencia lineal sencilla, especialmente cuando un transportista corrige posteriormente un escaneo. Conserva los valores sin procesar del proveedor junto con cualquier estado normalizado para que una persona pueda revisar los casos inciertos.

Los efectos secundarios requieren la misma disciplina que el almacenamiento. Una consulta que descubre «entregado» no debe enviar una segunda notificación de entrega si un webhook ya provocó una. Haz que las notificaciones y los procesos posteriores sean idempotentes frente a una clave empresarial duradera, como un identificador de envío más una transición definida o un ID de evento del proveedor. Por lo general, una actualización de base de datos y una notificación externa no pueden tratarse como una única operación automática; una salida transaccional o un registro de trabajo duradero equivalente puede ayudar a garantizar que un cambio confirmado vaya seguido de un único intento controlado de procesar su efecto secundario.

Ejecuta una recuperación acotada después de una interrupción

Las consultas rutinarias no sustituyen a un procedimiento de recuperación explícito. Cuando un endpoint de webhook, una cola o un proceso no haya estado disponible, identifica primero el periodo y el conjunto de envíos afectados. Incluye los envíos que estaban activos durante la interrupción, no solo los que actualmente aparecen como activos: alguno puede haber alcanzado un estado terminal mientras se perdían actualizaciones.

Inicia la recuperación con suficiente antelación respecto al fallo sospechado para tener en cuenta las entregas retrasadas y la incertidumbre sobre el momento de detección. Esta superposición reprocesa intencionadamente algunos datos conocidos; la idempotencia lo hace más seguro que dejar una brecha. Procesa los resultados en lotes manejables, registra el progreso de forma duradera y conserva los elementos fallidos para reintentarlos. No avances un punto de control de recuperación simplemente porque se haya solicitado una página. Avánzalo solo después de que los registros de la página se hayan procesado o se hayan registrado explícitamente como no resueltos.

Si la API ofrece paginación, verifica su orden y su comportamiento de continuación antes de utilizar un número de página o un cursor como punto de control de recuperación. Si solo ofrece instantáneas por envío, crea la lista de envíos afectados a partir de tus propios registros y reconcilia cada uno. Documenta el límite de este método: los estados actuales resultantes pueden ser correctos aunque algunos escaneos intermedios sigan sin estar disponibles.

Prueba los casos de fallo que esperas reparar

Un plan de pruebas útil va más allá de enviar un webhook y comprobar una respuesta de la API. Prueba entregas duplicadas de webhooks, un webhook antiguo que llega después de uno nuevo, una respuesta de consulta que llega después de un webhook, fallos parciales de la API, reinicios de procesos y un fallo entre el guardado del estado del envío y la programación de una notificación. Verifica tanto el registro visible del envío como el registro de efectos secundarios.

Prueba también una recuperación de interrupción con más registros de los que caben en un lote. Confirma que reiniciar el trabajo repite de forma segura una pequeña cantidad de trabajo en lugar de omitir registros. Cuando la API devuelva eventos históricos, comprueba si el mismo escaneo aparece en los formatos de webhook y consulta y si tu regla de deduplicación lo reconoce. Cuando la API devuelva solo instantáneas, confirma que tu interfaz no presente un evento intermedio inferido como un escaneo observado del transportista.

La supervisión operativa debe distinguir tres señales: la salud de la entrega de webhooks, la salud de las consultas y la frescura de los datos. Entre las medidas útiles se incluyen la antigüedad de la última reconciliación correcta de los envíos aptos, el número de discrepancias no resueltas, la antigüedad de la cola, las tasas de error de la API y el tamaño de la cola de recuperación. Un endpoint de webhook saludable por sí solo no demuestra que el estado local de los envíos esté actualizado.

Aplica la guía a una API de seguimiento

Para una integración de seguimiento de envíos, comienza con los identificadores documentados por el proveedor, las cargas útiles de los webhooks, las respuestas de consulta de envíos, los requisitos de autenticación y las restricciones de solicitudes. Si utilizas la API de seguimiento de 17TRACK, consulta su documentación oficial de la API antes de implementar el proceso de consultas. Confirma los mecanismos de consulta y actualización disponibles para tu integración en lugar de suponer que todas las cuentas o endpoints admiten la reproducción histórica, la recuperación basada en cursores o las solicitudes condicionales.

La decisión de implementación no es «webhooks o consultas». Usa webhooks para reducir la latencia normal de las actualizaciones, consultas para detectar y reparar las discrepancias que la API disponible pueda revelar y un procedimiento explícito de recuperación para los incidentes. Indica el límite de recuperación en tu manual operativo: si el sistema puede restaurar el estado actual, el historial de eventos o ambos. Ese límite determina si una actualización perdida se convierte en una vista obsoleta de corta duración o en una brecha permanente del registro.

Preguntas frecuentes

¿Pueden las consultas garantizar que no se pierda ningún evento de seguimiento?

No. Una consulta del estado actual puede revelar que el último estado ha cambiado, pero no puede recuperar un evento intermedio que la API no devuelva. La recuperación de eventos históricos requiere un historial de eventos disponible y una forma fiable de identificar o comparar sus entradas.

¿Debe un webhook activar una consulta inmediata de la API?

Solo cuando la consulta de la API añada información que tu aplicación necesite o cuando el webhook sea intencionadamente una notificación de cambio y no un registro completo. Consultar después de cada webhook puede crear solicitudes redundantes. Si el webhook contiene datos suficientes y fiables, procésalo directamente y deja las comprobaciones de la API para la reconciliación programada o la investigación específica.

¿Qué ocurre si la consulta de la API y el webhook no coinciden?

Compara las marcas de tiempo del proveedor, las versiones, los identificadores y el significado de las cargas útiles antes de seleccionar un estado actual. Conserva ambas observaciones. Si el proveedor no ofrece una señal de ordenación fiable y la discrepancia afecta a una acción importante, marca el envío para revisión en lugar de elegir silenciosamente la respuesta que llegó en último lugar.

¿Cuándo debe detenerse la consulta de un envío entregado?

Aplica una política documentada basada en si las correcciones tardías del transportista, los datos de comprobante de entrega o los flujos de trabajo posteriores son relevantes para tu aplicación. Un estado que parece terminal por sí solo no demuestra que el proveedor nunca vaya a actualizar de nuevo el registro.

¿Cómo debe gestionar el proceso de consultas la limitación de velocidad?

Reduce la presión de las solicitudes, reintenta con retroceso progresivo y respeta el encabezado Retry-After cuando el servidor lo proporcione. Da prioridad a los envíos con mayor necesidad de recuperación en lugar de reintentar repetidamente todos los envíos a la vez. La semántica HTTP define la respuesta 429 Too Many Requests y el campo Retry-After; aun así, deben comprobarse los límites específicos de cada endpoint en la documentación del proveedor.

Fuentes