Webhooks

Un webhook avisa a tu sistema cuando pasa algo en Volao, sin que tengas que consultar la API cada cierto tiempo. Volao envía una petición POST con un JSON a una URL tuya.

Por ahora hay un solo evento: el cambio de estado de una orden.

:::warning Lo configura un desarrollador de Volao No hay un endpoint para registrar, cambiar ni desactivar el webhook. Un desarrollador de Volao lo configura en tu cliente API con la URL que le indiques. Para activarlo, cambiar la URL o desactivarlo, escribe al equipo de Volao. :::

Cómo funciona

1. El estado o subestado de una de tus órdenes cambia.
2. Volao envía un POST a tu URL con los datos de la orden y del nuevo estado.
3. Tu servidor responde con un código 2xx.

• Un eventoCada cambio de estado o subestado de una orden genera un aviso.
• 15 segundosTiempo máximo que Volao espera la respuesta de tu servidor.
• Sin reintentosSi tu servidor falla o no responde a tiempo, el aviso no se vuelve a enviar.

Para activarlo, sigue estos pasos:

Prepara una URL

Publica un endpoint que:

• Use HTTPS y sea accesible desde internet.
• Acepte POST con Content-Type: application/json.
• Responda con un código 2xx (por ejemplo, 200). Volao no lee el cuerpo de tu respuesta.

Envía la URL al equipo de Volao

Indica la URL y el client_id del cliente API al que pertenece. Un desarrollador de Volao registra el webhook y lo activa.

Prueba con una orden

Cuando te confirmen la activación, crea una orden de prueba (Crear tu primer envío) y revisa que lleguen los avisos cuando cambie su estado.

La petición que recibes

Volao envía un POST a tu URL con este header y este cuerpo:

Header

Content-Type: application/json

Cuerpo

{
  "eventCode": "<código del evento>",
  "generatedAt": "2026-10-07 14:30:05",
  "order": {
    "orderId": "0199a1b2-7777-7e5f-8a6b-1c2d3e4f0008",
    "comprobante": "29137811",
    "createdAt": "2026-10-07 10:15:00",
    "deliveredAt": null,
    "onDelivery": true,
    "consignmentValue": 25.5,
    "deliveryCost": 3.5,
    "totalWeight": 2,
    "packageCount": 1,
    "productDescription": "Ropa",
    "comments": "Entregar en horario de oficina",
    "cancellationReason": null
  },
  "trackingMovement": {
    "statusMainCode": "IN_ROUTE",
    "statusMainCodeName": "En ruta de entrega",
    "statusMainDescription": "En ruta de entrega",
    "subStatusCode": "IN_ROUTE",
    "subStatusCodeName": "En ruta de entrega",
    "subStatusDescription": "En ruta de entrega",
    "statusColor": "#1565C0",
    "statusIcon": "fa-solid fa-truck",
    "dateMovement": "2026-10-07 14:30:00",
    "datetimeMovementFormatted": "07/10/2026 2:30 p. m."
  }
}

Campos generales

Campo	Tipo	Descripción
eventCode	string	Código del evento. Hoy siempre corresponde al cambio de estado de una orden.
generatedAt	string	Fecha y hora en que Volao generó el aviso.
order	object	Datos de la orden.
trackingMovement	object	El movimiento de seguimiento que generó el aviso: el nuevo estado de la orden.

order

Campo	Tipo	Descripción
orderId	string (UUID)	ID de la orden. Es el que usas en el resto de la API.
comprobante	string	Número de comprobante de la guía.
createdAt	string	Fecha y hora de creación de la orden.
deliveredAt	string | null	Fecha y hora de entrega; null si todavía no se entrega.
onDelivery	boolean	true si el cobro es contra entrega.
consignmentValue	number	Monto a cobrar al destinatario.
deliveryCost	number	Costo del envío.
totalWeight	number	Peso total del envío.
packageCount	number	Cantidad de paquetes.
productDescription	string	Descripción del contenido del paquete.
comments	string	Comentarios de la orden.
cancellationReason	string | null	Motivo de cancelación; null si la orden no está cancelada.

trackingMovement

Campo	Tipo	Descripción
statusMainCode	string	Código del estado principal (por ejemplo, IN_ROUTE).
statusMainCodeName	string	Nombre del estado principal.
statusMainDescription	string	Descripción del estado principal, en español.
subStatusCode	string	Código del subestado.
subStatusCodeName	string	Nombre del subestado.
subStatusDescription	string	Descripción del subestado, en español.
statusColor	string	Color del estado, en hexadecimal.
statusIcon	string	Clase del ícono del estado (Font Awesome).
dateMovement	string	Fecha del movimiento (YYYY-MM-DD HH:mm:ss).
datetimeMovementFormatted	string	Fecha del movimiento con formato legible.

Los estados y subestados posibles están en Obtener estados de orden y Obtener subestados de un estado.

Buenas prácticas

• Responde rápido. Devuelve 200 en cuanto recibas el aviso y procésalo después (por ejemplo, en una cola). Si tardas más de 15 segundos, Volao lo da por fallido.
• No dependas solo del webhook. Como no hay reintentos, un aviso puede perderse si tu servidor está caído. Consulta el estado con GET /api/orders/tracking?OrderId=... (Obtener el resumen de seguimiento de una orden) para revisar las órdenes que no se actualizaron.
• Acepta avisos repetidos o desordenados. Los avisos se envían por separado y pueden llegar en otro orden. Usa orderId + subStatusCode + dateMovement para detectar duplicados, y quédate con el movimiento de dateMovement más reciente.
• Verifica antes de una acción importante. La petición no incluye firma ni header de autenticación. Mantén tu URL en privado y, antes de hacer algo importante (por ejemplo, liberar un pago), confirma el estado consultando la API con orderId.