EN
CZ
DE
PL
ES
FR
IT
HU
SK
UA
EL
Webhooks salientes fiables: estado de entrega claro para cada integración
La integración con almacén, ERP o portal de transporte no está pensada para comprobar cada pocos segundos si algo ha cambiado en el Control de Franjas Temporales. Los webhooks salientes reenvían un evento a medida que ocurre, manteniendo claro el resultado de cada intento de entrega.
Desde el evento hasta la entrega sin encuestas
Cuando cambia una reserva o pedido, TSC crea un evento y selecciona las suscripciones activas de webhook que rastrean ese tipo. Cada suscripción recibe un JSON versionado vía HTTP POST hasta su dirección de destino.
- TSC detecta el cambio y crea un evento único.
- Las suscripciones activas se comparan con su tipo.
- Se creará una entrega separada para cada pedido correspondiente.
- La respuesta del sistema objetivo determina el estado resultante o el siguiente intento.
El procesamiento es impulsado por eventos y se realiza de forma asíncrona. El sistema conectado no tiene que cargar la API con consultas frecuentes de sondeo y puede responder poco después del cambio real.
El registro de entregas sustituye a las conjeturas
El administrador puede ver la entrega en un solo lugar y filtrarla tanto por suscripción al webhook como por estado. Para cada registro, hay un tipo de evento, número de intentos, último estado HTTP, hora del último intento y una breve información de error.
| Estado | ¿Qué significa esto? |
|---|---|
| Pending | La entrega espera en la cola para el primer o siguiente intento. |
| Delivered | El sistema objetivo devolvía una respuesta HTTP exitosa. |
| Failed | El último intento terminó en un error temporal y se repetirá. |
| DeadLetter | Los intentos automáticos han terminado o la respuesta no debe repetirse automáticamente. |
Qué ocurre cuando el sistema objetivo no está disponible
Los errores de red, las respuestas HTTP 429 y los errores del servidor 5xx se repiten con intervalos crecientes, en un máximo de cinco intentos. Los errores comunes del cliente 4xx excepto 429 pasan directamente al estado DeadLetter, porque el siguiente intento automático normalmente termina igual.
Tras reparar el sistema receptor, el usuario autorizado puede usar Resend. TSC restablece el número de intentos, elimina el último error y devuelve la entrega a la cola. Por tanto, no es necesario recuperar el evento empresarial original.
Eventos que corresponden al tráfico real
El catálogo no termina con creación, modificación y eliminación genéricas. Una integración también puede eliminar puntos específicos en el ciclo de vida de la reserva y el pedido, como reservation.pendingLibroreservation.processingstartedreservation.markedasarrivalreservation.approval.approvedreservation.vehicle.platechangedreservation.markedasdeparted, A o order.confirmedA.
La suscripción selecciona solo los eventos que necesita. El sistema objetivo no tiene por qué derivar retroactivamente del cambio general lo que realmente ocurrió en la operación.
Mensajes firmados y procesamiento seguro
La dirección del webhook utiliza HTTPS. TSC envía un envoltorio JSON con schemaVersioncampos yeventeventIdtenantIddataoccurredAt . El cuerpo de la solicitud está firmado con HMAC-SHA256, y el destinatario recibe una firma en la X-TSC-Signature cabecera junto con una marca de tiempo.X-TSC-Timestamp
El sistema receptor debe validar la firma y la marca de tiempo, procesarlas eventId idempotentemente y devolver un estado 2xx exitoso solo después de haber recibido el mensaje de forma segura. El secreto puede rotarse cuando se cambie la seguridad.
¿Qué aporta a las operaciones de integración?
- Menos consultas de encuestas y menos carga para ambos lados de la integración.
- Estado legible de cada entrega sin necesidad de buscar en varias herramientas de registro,
- Recuperación automática de errores temporales
- Reintento manual controlado después de que el sistema objetivo ha sido reparado.
- Origen e integridad verificables de cada mensaje.
El resultado no solo es una transmisión más rápida de los eventos, sino también una integración operativamente predecible: el equipo puede ver qué se ha entregado, qué espera el siguiente intento y qué requiere intervención.
¿Quieres conectar TSC a un ERP, WMS o a tu propia plataforma de integración? Explora las opciones de integración o descríbenos tu situación.