# order.updated

# Introduction

The order.updated webhook is triggered whenever an order status changes. You will receive real-time notifications at the webhook URL you configured in the Integrator Studio during app creation.

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

# Order Statuses

Status	Description
`pending`	Order received and waiting to be assigned to a driver
`dispatched`	Order assigned to a driver who is heading to the pickup location
`waiting_pack`	Driver arrived at pickup location and waiting for the order
`en_route`	Order picked up and driver is on the way to customer
`completed`	Order successfully delivered to customer
`canceled`	Order canceled (by merchant or system)
`failed`	Order failed to find an available driver

# Webhook Request

When an order status changes, Armada sends a POST request to your configured webhook URL.

# 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 event ID
`x-armada-webhook-topic`	`order.updated`

# Payload Schema

The request body contains the complete order details. For the full schema and field descriptions, see the Order Response Schema in the Order Management documentation.

# Payload Example

{
  "code": "EAA6CAC9D5",
  "status": "dispatched",
  "amount": 3,
  "created_at": "2026-01-07T20:13:25.615Z",
  "currency": "KWD",
  "delivery_fee": 3,
  "customer": {
    "name": "Nadeen",
    "phone": "212680980068",
    "address": "Salmiya, Block 7, St 74",
    "latitude": 29.3375,
    "longitude": 48.0657
  },
  "driver": {
    "name": "Driver-bot-144502",
    "phone": "09221909",
    "latitude": 29.99,
    "longitude": 47.699
  },
  "logistics": {
    "estimated_distance": 16648,
    "estimated_duration": 1595.3146000000002,
    "tracking_url": "https://sandbox.tracking.armadadelivery.com/618e4156-2da6-42f3-ae1c-3d85d5303bc0",
    "pickup_qr_url": "https://armada-sand.s3.eu-central-1.amazonaws.com/qrCodes/a5995085bdaf7314effcb2f6bab7f892.svg"
  }
}

# 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 updated.

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

Handle Idempotency: Use x-armada-webhook-id to track processed webhooks and avoid duplicate processing.

Validate Requests: Verify headers and consider IP whitelisting for security.

Log Events: Store webhook data for debugging and audit purposes.

# Use Cases

Update your application's order status in real-time as it progresses through different stages of delivery.

Send push notifications, SMS, or emails to customers when their order status changes.

Track delivery metrics, driver performance, and order completion rates.

Automate business processes based on order status changes (e.g., send surveys after completion).