Webhook de seguimiento: Explicación para desarrolladores y vendedores online

Un webhook de seguimiento es un mensaje HTTP push automatizado que transmite el estado del envío a otro sistema en tiempo real en cuanto cambia. En lugar de consultar constantemente una interfaz, el servicio de paquetería o la plataforma de envío envía el nuevo estado directamente a una URL proporcionada por el destinatario. Esto reduce la carga del servidor, disminuye significativamente la latencia en comparación con el sondeo y constituye la base técnica para los paneles de seguimiento, las notificaciones al cliente y los procesos aduaneros automatizados. Las siguientes secciones explican la tecnología subyacente, las medidas de seguridad necesarias y proporcionan un ejemplo de código concreto.

En resumen:

• El seguimiento mediante webhooks informa sobre los cambios de estado en tiempo real y reduce la carga del servidor a través de notificaciones push en comparación con el sondeo.
• La verificación de la firma se realiza utilizando el cuerpo de la solicitud sin modificar con HMAC-SHA256 para garantizar la autenticidad e integridad.
• Los eventos de webhook recibidos se colocan inmediatamente en una cola para evitar tiempos de espera y retrasos en el procesamiento.
• El sistema debe almacenar en caché los identificadores de eventos y procesarlos de forma idempotente para evitar de manera fiable las entregas duplicadas.
• Paket International simplifica la integración de webhooks a través de una interfaz central que agrupa los eventos de envío en un panel de control.

Contenido

• ¿Qué es un webhook de seguimiento? Definición y eventos de seguimiento típicos.
• ¿Cómo se estructura el mensaje de un webhook de seguimiento?
• ¿Cómo se protege un receptor de webhook?
• ¿Cómo se procesan los eventos de webhook sin riesgo de que se agoten los tiempos de espera?
• ¿Cómo sería un ejemplo de código para recibir un webhook?
• ¿Qué propósito específico cumplen los webhooks de seguimiento en el transporte marítimo?
• ¿Cómo se detectan los fallos de los webhooks antes que los clientes?
• Lista de verificación: Cómo poner en marcha un punto final de webhook en diez pasos
• Cómo una plataforma de envíos utiliza webhooks en la práctica
• Mar de fondo
• Preguntas Frecuentes

¿Qué es un webhook de seguimiento? Definición y eventos de seguimiento típicos.

Un webhook funciona de forma inversa a una API tradicional. Con una API normal, tu sistema consulta activamente si hay actualizaciones. Un webhook invierte este proceso: el remitente te notifica en cuanto ocurre algo, por lo que este patrón se suele denominar API inversa. En lugar de consultar con el servicio de paquetería cada minuto para ver si hay novedades, tu sistema registra una dirección de recepción una sola vez, y el remitente solo proporciona actualizaciones cuando es necesario.

En el contexto del envío, prácticamente cada cambio de estado desencadena un evento independiente. Los eventos de seguimiento típicos incluyen:

• Se ha creado la etiqueta de envío.
• El envío fue recogido por el servicio de paquetería.
• El envío fue escaneado en un centro de clasificación.
• El envío está en camino.
• El envío se entregó con éxito.

La ventaja es evidente: actualizaciones en tiempo real sin consultas repetidas, menor carga de procesamiento para ambas partes y una base natural para la automatización. La desventaja solo se hace patente durante el funcionamiento: el sistema debe estar siempre accesible, soportar interrupciones y gestionar mensajes duplicados o retrasados. Precisamente de esto tratan las siguientes secciones.

¿Cómo se estructura el mensaje de un webhook de seguimiento?

Técnicamente, un webhook de seguimiento es simplemente una solicitud HTTP POST a una URL que usted defina. La carga útil que llega casi siempre sigue un patrón de cuatro partes: un ID de evento único, un tipo de evento, una marca de tiempo y un objeto de datos que contiene la información real del envío. Este formato de sobre está tan extendido en la práctica que se ha convertido en sinónimo de... Estándar de facto para las cargas útiles de webhook sombrero establecido.

Además del cuerpo del mensaje, las cabeceras HTTP contienen información adicional importante. Content‑Type: application/json Esto incluye un encabezado de firma (a menudo). X‑Signature o en X‑Hub‑Signature‑256) y un ID de entrega, que permite distinguir los intentos de entrega individuales.

Un punto que a menudo se pasa por alto en la práctica: la firma debe estar encima de la cuerpo crudo e inalterado El hash debe calcularse antes de que cualquier biblioteca JSON lo analice. Incluso un cambio en el formato, como el uso de espacios diferentes, genera un hash distinto y, por lo tanto, provoca que el mensaje sea rechazado incorrectamente.

¿Cómo se protege un receptor de webhook?

Un destinatario solo está listo para la producción cuando responde de manera fiable a tres preguntas: ¿El mensaje proviene realmente del remitente indicado? ¿Ya se ha procesado? ¿Qué sucede si falla el procesamiento? Quien ignore estas tres preguntas, tarde o temprano recibirá confirmaciones de pedido duplicadas o declaraciones de aduana incompletas.

La verificación de firma mediante HMAC-SHA256 en el cuerpo sin procesar es el primer paso. El secreto compartido entre el remitente y el receptor genera un hash, que el receptor recalcula y compara. El tipo de comparación es crucial: una comparación de cadena normal con === Es claramente inseguro porque se detiene inmediatamente ante cada carácter incorrecto, revelando así una diferencia de tiempo que los atacantes pueden explotar. En Node.js, esto se gestiona mediante... crypto.timingSafeEqual Esta tarea es constante en el tiempo; en Python, la correspondiente compare_digest-Funcion.

• Siempre verifique la firma utilizando el texto sin procesar ni modificar, nunca el objeto ya analizado.
• Para evitar ataques de repetición con mensajes antiguos pero firmados válidamente, compruebe la marca de tiempo en la carga útil comparándola con un intervalo de tiempo de aproximadamente cinco minutos.
• Almacene en caché los ID de eventos procesados ​​previamente para evitar el procesamiento duplicado de entregas repetidas.
• Para imponer técnicamente la idempotencia, por ejemplo mediante una inserción atómica en la base de datos con una restricción UNIQUE o una SET NX en Redis
• Los eventos que finalmente hayan fallado después de varios intentos deberían trasladarse a una cola de mensajes no entregados en lugar de ser descartados silenciosamente.

Esta combinación de marcas de tiempo firmadas y almacenamiento en caché de ID para protegerse contra ataques de repetición también se utiliza comúnmente. Guías de seguridad para webhooks empfohlen.

Importante para gestionar las expectativas: Casi todos los remitentes de webhooks operan bajo el principio de "al menos una vez", lo que significa que realizan la entrega al menos una vez. En la práctica, esto implica que las entregas duplicadas son la norma, no un error. Un sistema que no procesa de forma idempotente tarde o temprano generará notificaciones de envío duplicadas o estados aduaneros incorrectos.

Consejo profesional: No elimine los ID de eventos almacenados en caché inmediatamente después de su procesamiento, sino solo después de que haya expirado el plazo de reintento del remitente. Muchos proveedores repiten los intentos fallidos de entrega durante varias horas o días, y un ID eliminado demasiado pronto crea precisamente la brecha que la comprobación de idempotencia debería cerrar.

¿Cómo se procesan los eventos de webhook sin riesgo de que se agoten los tiempos de espera?

El mayor riesgo operativo de los webhooks no es la seguridad, sino el tiempo de respuesta. Los servicios de paquetería y las plataformas de envío imponen límites de tiempo estrictos: algunos proveedores esperan una respuesta 2xx en cuestión de segundos, mientras que otros permiten hasta 30 segundos, como describe GitHub en sus recomendaciones. Si se supera este plazo, el remitente considera que la entrega ha fallado y la reenvía, saturando la base de datos con aún más duplicados.

La solución consiste en una estricta separación entre recepción y procesamiento:

1. Verifique al instante datos brutos y firmas sin necesidad de lógica empresarial compleja.
2. Escribe el evento en una cola, por ejemplo, usando BullMQ, Amazon SQS o pg-boss.
3. Inmediatamente con 200 OK Responda antes de que comience el procesamiento real.
4. Un proceso en segundo plano independiente recupera la tarea de la cola y ejecuta la lógica correspondiente.
5. El ID del trabajo en la cola corresponde al ID del evento, por lo que la propia cola también se desduplica.

Quien gestione el procesamiento de webhooks de forma síncrona dentro de la propia solicitud, tarde o temprano se encontrará con un conflicto con el tiempo de espera del remitente. Los eventos deben ponerse en cola inmediatamente; el procesamiento real se ejecuta de forma asíncrona en segundo plano.

El TTL de idempotencia, es decir, el tiempo que un ID de evento permanece en la caché, debe basarse en la ventana de reintento real del remitente, no en un número arbitrario. Para la planificación de capacidad, conviene considerar la profundidad de la cola: si crece continuamente, el proceso procesa los eventos más lentamente de lo que llegan, y se deben implementar mecanismos de contrapresión antes de que se produzcan desbordamientos de memoria. Se debe implementar una alerta para la cola de mensajes no entregados desde el principio, ya que un aumento en esta suele ser la primera señal de alerta de un problema más grave.

¿Cómo sería un ejemplo de código para recibir un webhook?

Un manejador limpio siempre sigue el mismo orden: primero verificar, luego almacenar, luego procesar. El siguiente flujo se basa en patrones comunes de Node.js y se puede adaptar a cualquier lenguaje que admita HMAC y operaciones atómicas de base de datos.

1. Lee el cuerpo de la solicitud en formato sin modificar, sin analizarlo previamente.
2. Extrae la firma enviada desde el encabezado.
3. Utilizando la clave secreta compartida, calcule la firma HMAC-SHA256 esperada a partir del texto sin procesar.
4. Compare ambas firmas utilizando una función de constante de tiempo, sin usar nunca un simple operador de igualdad.
5. Analice el cuerpo como JSON solo después de una verificación exitosa.
6. Escriba el ID del evento de forma atómica en la base de datos, por ejemplo, utilizando una restricción UNIQUE que rechace automáticamente los duplicados.
7. Coloca el evento en la cola de procesamiento.
8. Inmediatamente con 200 OK respuesta.

El motivo del orden en el paso 5 es sencillo: cualquiera que analice JSON antes de verificar la firma está procesando datos potencialmente manipulados, incluso si el procesamiento en sí parece inofensivo. Primero validar, luego interpretar.

Cuando se producen errores, la semántica HTTP correcta es fundamental. 4xx-El estado indica al remitente que "este mensaje tiene un fallo fundamental, no lo repita", por ejemplo, en el caso de una firma incorrecta. 5xx-El estado significa "algo no funciona correctamente de mi parte, por favor inténtelo de nuevo más tarde", por ejemplo, en caso de un fallo de la base de datos.

Consejo profesional: Registra cada firma rechazada con su fecha y hora y dirección IP de origen. Un aumento repentino en las comprobaciones de firmas fallidas suele ser el primer indicio de una configuración incorrecta del secreto tras una rotación, no de un ataque.

¿Qué propósito específico cumplen los webhooks de seguimiento en el transporte marítimo?

En el día a día de una tienda online, los webhooks de seguimiento se encargan de tareas que antes requerían seguimiento manual. En cuanto un servicio de paquetería informa de un nuevo escaneo, el webhook actualiza automáticamente la página de seguimiento pública, envía una notificación a los clientes o inicia un paso interno de gestión de pedidos, como la aprobación de una factura tras la entrega.

• Las páginas de seguimiento muestran el estado actual sin la demora causada por la verificación manual.
• Las notificaciones a los clientes se envían automáticamente por correo electrónico o SMS ante cada cambio de estado relevante.
• Los sistemas internos, como los de tienda, ERP o CRM, reciben el nuevo estado a través de una carga útil simplificada, sin que nadie tenga que introducir datos manualmente.
• Las consultas a través de WISMO ("¿Dónde está mi pedido?") están disminuyendo significativamente porque los clientes pueden consultar el estado de sus pedidos ellos mismos.
• Los cambios de estado relevantes para la aduana pueden enviarse automáticamente a los sistemas aduaneros, sin necesidad de trámites en papel.

Importante: El webhook en sí a menudo solo proporciona información clave como el número de seguimiento y el estado actual. Para obtener información más detallada, algunos servicios de paquetería también hacen referencia a una API de seguimiento independiente, que se consulta según sea necesario. Aquellos que administran su tienda a través de WooCommerce o si se conecta a un sistema comparable, estos eventos generalmente se introducen directamente en el sistema de gestión de pedidos existente.

¿Cómo se detectan los fallos de los webhooks antes que los clientes?

Un sistema de webhook sin monitorización funciona a ciegas. Los indicadores clave de rendimiento (KPI) más importantes son la tasa de éxito de entrega (DSR), es decir, el porcentaje de entregas procesadas correctamente, la tasa de reintentos, la profundidad de calidad de entrega (DLQ) y la latencia de procesamiento entre la recepción y la finalización.

• Una tasa de éxito en las entregas inferior a la habitual indica un problema con la verificación de la firma o con la accesibilidad.
• Un aumento en la profundidad de la cola de mensajes no entregados (DLQ) indica que los eventos finalmente fallan, no solo se retrasan.
• Una alerta que se activa tras aproximadamente cinco fallos consecutivos en un punto final evita que un fallo se detecte solo después de varias horas.
• El aumento de la latencia de procesamiento suele ser el primer indicio de una cola sobrecargada.

La rigurosidad del umbral de alerta depende del tipo de evento: para eventos relacionados con pagos, se justifica una alerta incluso después de un solo intento fallido, mientras que para eventos puramente analíticos, una tolerancia mayor es suficiente. Antes de la puesta en marcha, se deben incluir en cada lista de verificación casos de prueba para entregas repetidas, cargas útiles con formato incorrecto y procesamiento de descarga/descarga ralentizado artificialmente.

Consejo profesional: Simule una interrupción total de su propio punto final durante cinco minutos y observe cómo se comporta la cola de reintentos del remitente. Esto le permitirá comprobar, antes de la puesta en marcha, si su cola de mensajes no entregados (DLQ) y sus alertas funcionan correctamente.

Lista de verificación: Cómo poner en marcha un punto final de webhook en diez pasos

1. Defina los eventos relevantes que su sistema realmente necesita.
2. Mantenga la carga útil lo más mínima posible; no se suscriba a campos innecesarios.
3. Forzar el uso de HTTPS y generar una clave secreta para la verificación de la firma.
4. Permitir el acceso al cuerpo de la solicitud sin procesar previamente.
5. Compruebe la firma HMAC mediante la comparación de la constante de tiempo.
6. Escriba el ID del evento de forma atómica en la base de datos para evitar duplicados.
7. Coloca el evento en una cola de procesamiento.
8. Dentro del plazo establecido por el remitente con 200 OK respuesta.
9. Configura una cola de mensajes no entregados y alertas para eventos fallidos.
10. Documente sus propias expectativas con respecto a los eventos, los campos y el comportamiento de reintento.

Cómo una plataforma de envíos utiliza webhooks en la práctica

Quienes desarrollan sus propios webhooks de seguimiento se dan cuenta rápidamente de la cantidad de trabajo operativo que implica la verificación de firmas, las colas y la lógica del estado aduanero antes de que la primera actualización de estado llegue de forma fiable al cliente. Paket International se encarga precisamente de esta parte de la cadena de envíos y automatiza las actualizaciones de estado, los activadores aduaneros y el seguimiento centralizado de los envíos, de modo que los minoristas en línea no tienen que crear su propio receptor de webhook para cada servicio de paquetería.

La plataforma conecta servicios de paquetería como DHL, UPS, FedEx, DPD y DB Schenker a través de una interfaz común y consolida sus envíos en una ubicación central. Panel de seguimientoLas integraciones de API y plugins, por ejemplo para WooCommerce o sistemas de comercio electrónico similares, permiten que estos eventos se incorporen directamente a los procesos existentes, en lugar de conectar cada proveedor individualmente. Esto no solo reduce el esfuerzo de desarrollo, sino que también disminuye los costos. laut Según Paket International, los costos de envío se reducen significativamente porque el despacho de aduanas y la creación de documentos se automatizan en lugar de procesarse manualmente. Cualquiera que confíe el envío internacional, incluido el despacho de aduanas, a una Plataforma de envío quien desee entregarlo puede encontrarlo debajo del tarifas de envío actuales El punto de partida adecuado para su propio volumen de envíos.

Preguntas Frecuentes

¿Qué es un webhook? Explicado de forma sencilla.

Un webhook es un mensaje automatizado que un sistema envía a otro en cuanto se produce un evento específico, como un cambio en el estado de un envío. A diferencia de una consulta tradicional, el destinatario no tiene que comprobarlo constantemente, sino que recibe una notificación inmediata en cuanto hay alguna novedad.

¿Cómo programo un webhook?

Para recibir el evento, se configura un punto final HTTPS que lee el cuerpo de la solicitud sin procesar, verifica la firma adjunta mediante una comparación de constante de tiempo y solo entonces procesa el evento como JSON. A continuación, se escribe de forma atómica el ID del evento en una base de datos, se coloca la tarea en una cola y se responde de inmediato. 200 OK, para que el remitente no repita la entrega.

¿Qué distingue a un webhook de una consulta API clásica?

Con una API tradicional, su sistema solicita activamente nuevos datos, a menudo a intervalos fijos, incluso si no ha habido ningún cambio. Un webhook invierte este proceso: el remitente solo envía una solicitud cuando se ha producido un evento, lo que reduce la carga del servidor y la latencia.

¿Cómo puedes protegerte contra las entregas duplicadas de webhooks?

Las entregas duplicadas son normales para la mayoría de los remitentes de webhooks, ya que muchos proveedores operan bajo el principio de "entregar al menos una vez". Una inserción atómica en la base de datos con una restricción UNIQUE en el ID del evento o una SET NX En Redis, esto impide que un evento que ya ha sido procesado se ejecute de nuevo.

¿Ofrece Paket International su propia integración de webhook?

Paket International consolida los envíos de múltiples servicios de paquetería en un panel de seguimiento centralizado y pone esta información a disposición de los sistemas de las tiendas mediante integraciones de API y plugins. Los detalles sobre las opciones de integración técnica y los términos y condiciones vigentes se pueden consultar directamente en [nombre del sitio web/plataforma]. Página de la plataforma.

recomendaciones

• Minoristas en línea: Automatización del envío (internacional)
• Plugin de envío de WooCommerce para facilitar los envíos con trámites aduaneros.
• Etsy: Automatice sus envíos internacionales
• Envíos de PrestaShop: Entrega internacional, etiquetas y aduanas