Webhooks

A webhook tells your system when something happens in Volao, so you don't have to poll the API. Volao sends a POST request with a JSON body to a URL of yours.

For now there is a single event: an order status change.

:::warning Set up by a Volao developer There is no endpoint to register, change or disable the webhook. A Volao developer sets it up on your API client with the URL you provide. To enable it, change the URL or disable it, contact the Volao team. :::

How it works

1. The status or sub-status of one of your orders changes.
2. Volao sends a POST to your URL with the order data and the new status.
3. Your server responds with a 2xx code.

• One eventEvery status or sub-status change of an order sends a notification.
• 15 secondsMaximum time Volao waits for your server to respond.
• No retriesIf your server fails or does not respond in time, the notification is not sent again.

To enable it, follow these steps:

Prepare a URL

Publish an endpoint that:

• Uses HTTPS and is reachable from the internet.
• Accepts POST with Content-Type: application/json.
• Responds with a 2xx code (for example, 200). Volao does not read the body of your response.

Send the URL to the Volao team

Provide the URL and the client_id of the API client it belongs to. A Volao developer registers the webhook and enables it.

Test it with an order

Once the activation is confirmed, create a test order (Create your first shipment) and check that the notifications arrive when its status changes.

The request you receive

Volao sends a POST to your URL with this header and this body:

Header

Content-Type: application/json

Body

{
  "eventCode": "<event code>",
  "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."
  }
}

General fields

Field	Type	Description
eventCode	string	Event code. Today it always corresponds to an order status change.
generatedAt	string	Date and time Volao generated the notification.
order	object	Order data.
trackingMovement	object	The tracking movement that triggered the notification: the order's new status.

order

Field	Type	Description
orderId	string (UUID)	Order ID. It is the one you use in the rest of the API.
comprobante	string	Receipt number of the shipping label.
createdAt	string	Date and time the order was created.
deliveredAt	string | null	Delivery date and time; null if it has not been delivered yet.
onDelivery	boolean	true if payment is collected on delivery.
consignmentValue	number	Amount to collect from the recipient.
deliveryCost	number	Shipping cost.
totalWeight	number	Total shipment weight.
packageCount	number	Number of packages.
productDescription	string	Description of the package contents.
comments	string	Order comments.
cancellationReason	string | null	Cancellation reason; null if the order is not cancelled.

trackingMovement

Field	Type	Description
statusMainCode	string	Main status code (for example, IN_ROUTE).
statusMainCodeName	string	Main status name.
statusMainDescription	string	Main status description, in Spanish.
subStatusCode	string	Sub-status code.
subStatusCodeName	string	Sub-status name.
subStatusDescription	string	Sub-status description, in Spanish.
statusColor	string	Status color, in hexadecimal.
statusIcon	string	Status icon class (Font Awesome).
dateMovement	string	Movement date (YYYY-MM-DD HH:mm:ss).
datetimeMovementFormatted	string	Movement date in a readable format.

The possible statuses and sub-statuses are listed in Get order statuses and Get the sub-statuses of a status.

Best practices

• Respond quickly. Return 200 as soon as you receive the notification and process it afterwards (for example, in a queue). If you take more than 15 seconds, Volao treats it as failed.
• Don't rely on the webhook alone. Since there are no retries, a notification can be lost if your server is down. Check the status with GET /api/orders/tracking?OrderId=... (Get an order's tracking summary) to review orders that were not updated.
• Accept repeated or out-of-order notifications. Notifications are sent independently and may arrive in a different order. Use orderId + subStatusCode + dateMovement to detect duplicates, and keep the movement with the most recent dateMovement.
• Verify before an important action. The request carries no signature or authentication header. Keep your URL private and, before doing something important (for example, releasing a payment), confirm the status by querying the API with orderId.