# order.location.updated

# Introduction

The order.location.updated webhook provides real-time location tracking for orders in transit. This webhook is triggered recurrently while the order status is en_route, sending periodic updates based on the configuration you set during app creation in the Integrator Studio.

This allows you to display live delivery tracking on maps or provide real-time updates to your customers.

For more details on webhook configuration, see the App Creation section.

# Alternative Tracking Option

Tip

You can also use the tracking_url from your created order response. This URL provides a ready-made UI for your customers to track their order live. You can embed it in your dashboard inside an iframe or share it directly with customers.

# How It Works

Trigger Condition: Only fires when order status is en_route (driver has picked up the order and is heading to customer)
Frequency: Configurable interval set during app creation in Integrator Studio
Duration: Continues until order reaches completed or canceled status
Webhook ID: The same x-armada-webhook-id is used for all location updates in the sequence until the event stops

# Webhook Request

Armada sends recurrent POST requests to your configured webhook URL with the latest order location.

# Payload Headers

These are the useful headers you need. The request may include additional headers, but these are the essential ones:

Header	Description
`Content-Type`	`application/json`
`User-Agent`	`Armada Delivery Solutions`
`x-armada-app-id`	Your application ID
`x-armada-app-name`	Your application name
`x-armada-installation-id`	Installation identifier
`x-armada-api-version`	API version (`v1`)
`x-armada-timestamp`	Webhook sent timestamp (ISO 8601)
`x-armada-webhook-id`	Unique webhook sequence ID (same for all updates in this sequence)
`x-armada-webhook-topic`	`order.location.updated`

# Payload Schema

{
  "code": "String", // Order code
  "location": { // Current order location
    "latitude": Number, // Current latitude
    "longitude": Number // Current longitude
  },
  "status": "String" // Always "en_route" for this webhook
}

# Payload Example

{
  "code": "EAA6CAC9D5",
  "location": {
    "latitude": 29.3469,
    "longitude": 47.9246
  },
  "status": "en_route"
}

# Response Requirements

Your webhook endpoint must respond with a 200 status code to acknowledge receipt.

# Best Practices

Identify the Merchant: Use x-armada-app-id and x-armada-installation-id headers together to identify which merchant installation is being tracked.

Track Sequence: The x-armada-webhook-id remains the same for all location updates in a single delivery sequence. Use it to group updates for the same order journey.

Respond Quickly: Return 200 OK immediately upon receiving the webhook, then process location data asynchronously.

Handle Recurrence: Expect multiple webhook calls for the same order. Update your tracking display with each new location.

Validate Status: Always check that status is en_route before processing. If you receive any other status, ignore it - this could be a racing condition issue. Only process location updates when status is en_route.

Log Events: Store location history for debugging, analytics, and delivery route optimization.

# Use Cases

Display the driver's current location on a map in real-time, showing customers exactly where their order is.

Calculate and display estimated arrival time based on current location and distance to destination.

Send proactive notifications when the driver is approaching (e.g., "Your order is 5 minutes away!").

Analyze delivery routes, optimize future deliveries, and track driver efficiency.

Trigger actions when the driver enters specific geographical zones or gets close to the destination.