Webhook & Callback flow

Partners will need to provide a Webhook URL to receive order updated events from Ahamove. Ahamove will callback to this URL each time the order has updates.

How to test callback and Webhook

1. Implement webhook url to receive order_id & status, then send Ahamove the URL to config
2. Download AhaDriver STG app on Android device
3. Register an account, then contact to Ahamove to verify the account
4. Login and go online
5. Use API Create Order to create an order within 1km from the driver location
6. The driver app will receive a notification, click on the notification to accept the order
7. Ahamove server will trigger an event to webhook URL from ACCEPTED status
8. Try to update order status on the driver app, Ahmove server will trigger events to webhook URL with according order statuses

Authentication Method

Ahamove support 3 types of authorization header (API-KEY, BEARER-TOKEN, BASIC-AUTH)

API Key

Partners put the API key in the Authorization header

Header: { apikey: "auth_token" }

Ex: { "apikey": "KJhb4seu82dHe3hkDgyU7mQoh5AB1o" }

Bearer Token

Partners send the token in the Authorization header when making requests to protected resources

Header: { Authorization: "Bearer + auth_token" }

Ex: { "Authorization": "Bearer KJhb4seu82dHe3hkDgyU7mQoh5AB1o"}

Basic Auth

With this method, Partners place a username: password into the request header. The username and password are encoded with Base64

Header: { Authorization: "Basic {b64.StdEncoding.EncodeToString([]byte({username}:{password}))}" }

Ex: { "Authorization": "Basic KJhb4seu82dHe3hkDgyU7mQoh5AB1o"}

Callback Flow

Sample Callback

{
  "_id": "22VMV54W",
  "accept_time": 0,
  "board_time": 0,
  "cancel_by_user": false,
  "cancel_comment": "",
  "cancel_image_url": "",
  "cancel_time": 0,
  "city_id": "SGN",
  "complete_time": 0,
  "create_time": 1665742305.9305305,
  "currency": "VND",
  "order_time": 1665742305.9305305,
  "partner": "",
  "path": [
    {
      "address": "725 Hẻm số 7 Thành Thái, Phường 14, Quận 10, Hồ Chí Minh, Việt Nam",
      "cod": 0,
      "por_info": "",
      "short_address": "Quận 10",
      "formatted_address": "",
      "mobile": "09xxxxxxxx",
      "status": "",
      "complete_lat": 0,
      "complete_lng": 0,
      "fail_lat": 0,
      "fail_lng": 0,
      "complete_time": 0,
      "fail_time": 0,
      "return_time": 0,
      "pod_info": "",
      "fail_comment": "",
      "name": "Anh",
      "remarks": "call me"
    },
    {
      "address": "Chợ Bến Thành, Bến Thành, Quận 01, Hồ Chí Minh, Việt Nam",
      "cod": 0,
      "por_info": "",
      "short_address": null,
      "formatted_address": "",
      "mobile": "09xxxxxxxx",
      "status": "",
      "complete_lat": 0,
      "complete_lng": 0,
      "fail_lat": 0,
      "fail_lng": 0,
      "complete_time": 0,
      "fail_time": 0,
      "return_time": 0,
      "pod_info": "",
      "fail_comment": "",
      "name": "Bao"
    }
  ],
  "payment_method": "CASH",
  "pickup_time": 0,
  "service_id": "SGN-BIKE",
  "status": "ASSIGNING",
  "sub_status": "",
  "supplier_id": "",
  "supplier_name": "",
  "surcharge": 1.1,
  "user_id": "",
  "user_name": "",
  "total_pay": 33000,
  "promo_code": "",
  "stoppoint_price": 0,
  "special_request_price": 1000,
  "vat": 0,
  "distance_price": 32000,
  "voucher_discount": 0,
  "subtotal_price": 33000,
  "total_price": 33000,
  "surge_rate": 1.1,
  "api_key": "<API_KEY_STG>",
  "shared_link": "https://cloudstg.ahamove.com/share-order/22VMV54W/84911434061",
  "insurance_portal_url": "https://claim-dev.globalcare.vn/claim/ahamove/intransit?platform=app&code=22VMV54W&phone=84xxxxxxxxx",
  "app": "Ahamove",
  "store_id": 0,
  "distance": 4.68
}

Callback _id for Multi-Drop Orders (1 Pickup – N Deliveries)

For orders with one pickup point and multiple delivery points (1-N orders), the callback _id field works differently depending on which stop is being updated.

• Order-level callbacks (e.g., IDLE, ASSIGNING, ACCEPTED, COMPLETED, CANCELLED): The _id is the order ID with no suffix.
• Stop-level callbacks (i.e., when the driver updates the status of a specific delivery point, order status in IN PROCESS): The _id includes a numeric suffix indicating which delivery stop triggered the event.

Format:

{order_id}-{stop_index}

Where stop_index starts at 1 for the first delivery point, 2 for the second, and so on.

Example:

Given an order with ID 26ABCDEF that has 3 delivery stops:

Driver action	_id in callback
Updates status of delivery stop 1	26ABCDEF-1
Updates status of delivery stop 2	26ABCDEF-2
Updates status of delivery stop 3	26ABCDEF-3