# Webhooks

# Introduction

To receive real-time updates on the status of orders placed through your app, you can provide a webhook URL in the Armada delivery Merchant Dashboard or via API branch managements.

This is an example sequence diagram illustrating the process from order creation to dispatching to the driver:

sequenceDiagram
    participant Client
    participant "Our API" as API
    participant "Merchant Dashboard" as Dashboard
    participant "Webhook URL" as Webhook
    participant Driver

    Client->>API: Send order
    API->>Dashboard: Order appears
    API->>Webhook: Send webhook with status "Pending"
    Webhook-->>API: Confirmation received
    Driver->>API: Accept order
    API->>Webhook: Send webhook with status "Dispatched"
    Webhook-->>API: Confirmation received
    API->>Dashboard: Update status to "Dispatched"
    Dashboard-->>Client: Order status updated

# Status

Get real-time updates on order status changes with our API, which sends instant notifications by a POST request to your webhook URL whenever there's a change.

Here is a table of statuses:

Status	Description
`pending`	The order has been received and is waiting to be dispatched to a driver
`dispatched`	The order has been dispatched to a driver who is on his way to the merchant
`en_route`	The order has been picked up from the merchant and is on the way to the customer
`complete`	The order has been successfully delivered
`canceled`	The order has been canceled from your end
`failed`	The order has failed to find a driver

# Payload

Upon each status change, you will receive the following information:

In headers:

Authorization: The value of your order-webhook-key you provide when you create the order (see order creation).

The body:

code: Identifier for the delivery within Armada String
deliveryFee: Cost of the delivery Number
amount: Order amount set by the merchant Number
customerAddress: Address generated by Armada based on platform data String
customerLocation: Customer's geographical coordinates Object
- latitude: Latitude Number
- longitude: Longitude Number
customerName: Customer's name String
customerPhone: Customer's phone number String
orderStatus: Status of the order String
estimatedDistance: Estimated distance from pickup to customer location (in meters) Number
estimatedDuration: Estimated duration from pickup to customer location (in seconds) Number
driver: Information about the assigned driver:
- name: Driver's name String
- phoneNumber: Driver's phone number String
- latitude: Driver's latitude Number
- longitude: Driver's longitude Number
trackingLink: URL for tracking delivery progress URL
qrCodeLink: URL for the delivery QR code, used for scanning URL
orderCreatedAt: Date and time of delivery creation ISO Date
currency: Currency used for the delivery String

# Example

Header
Authorization: vE6gH8Rt2L1sK9w

Body
{
  "code": "B1983149DA",
  "deliveryFee": 2,
  "amount": 5,
  "customerAddress": "Al-Adan, Block 5, St 104",
  "customerLocation": {
    "latitude": 29.22536,
    "longitude": 48.07328
  },
  "customerName": "mohamed",
  "customerPhone": "51234567",
  "orderStatus": "dispatched",
  "estimatedDistance": 24144,
  "estimatedDuration": 1788.2890000000002,
  "driver": {
    "name": "Anagipura Roshan",
    "phoneNumber": "10102005",
    "latitude": 29.372146666666662,
    "longitude": 47.988613333333326
  },
  "trackingLink": "https://sandbox.tracking.armadadelivery.com/5400bb82-5550-414c-b63f-78b96da68c58",
  "qrCodeLink": "https://armada-sand.s3.eu-central-1.amazonaws.com/qrCodes/51ecc71c0a57295370672190a13a4667.svg",
  "orderCreatedAt": "2024-02-22T12:49:43.409Z",
  "currency": "KWD"
}