Web Hooks


Introduction

Web Hooks are a convenient way to receive real time updates for your shipments as soon as a status is updated. Web Hooks can be used to update customer internal systems with the latest shipments statuses.

{info} The webhook URL call is scheduled as soon as the shipment status is updated in AyMakan system. The call may take from a few seconds to a few minutes.

Setup

There are two possible ways to setup webhooks for an account.

Setup Webhooks in Account Area

To setup Web Hook, login to your customer area. On left side menu, find Integrations and click on it. On next page, find Webhooks section.

There are several options to setup.

  • Webhook URL: The URL which will be called by AyMakan system whenever a shipment status is changed.
  • Request Type: The request type which AyMakan system will use to call Webhook URL. It should be always POST.
  • Authorization Key (Optional): Custom HTTP header name that will be sent when AyMakan calls your webhook URL (e.g., "X-Custom-Auth").
  • Authorization Value (Optional): Custom HTTP header value that will be sent with the authorization key when AyMakan calls your webhook URL.

{warning} AyMakan is only responsible for calling the provided Web Hook URL. Security of that URL should be handled by your end.

{info} If you provide authorization credentials, they will be sent as HTTP headers when AyMakan calls your webhook URL. This allows you to verify that webhook requests are coming from AyMakan.

Request

When calling the Webhook URL, AyMakan sends a POST request with the following headers:

  • Content-Type: application/json
  • Accept: application/json
  • : <authorization-value>

{info} The custom authorization header is only included if you have configured authorization credentials in your webhook settings. You provide these credentials when creating or updating your webhook, and AyMakan will send them as HTTP headers with every webhook request.

The request body includes comprehensive shipment data:

Core Fields

  • tracking_number: The tracking number of the shipment
  • reference: Customer-provided shipment reference
  • status: Status code (e.g., AY-0003, AY-0005)
  • status_label: Human-readable status description
  • date_time: Timestamp when the status was updated

Reason Fields (for Not Delivered/Pending statuses)

  • reason_code: Reason code (e.g., AY-0048 for Future Delivery)
  • reason_en: English description of the reason

Delivery Information

  • delivery_name: Recipient name
  • delivery_email: Recipient email
  • delivery_city: Delivery city
  • delivery_address: Full delivery address
  • delivery_postcode: Postal code
  • delivery_country: Country code (e.g., "SA")
  • delivery_phone: Recipient phone number
  • delivery_description: Package description
  • delivery_neighbourhood: Delivery neighbourhood
  • requested_delivery_date: Customer-requested delivery date

Collection Information

  • collection_name: Sender/collection point name
  • collection_email: Sender email
  • collection_city: Collection city
  • collection_address: Collection address
  • collection_neighbourhood: Collection neighbourhood

Shipment Details

  • pieces: Number of pieces
  • weight: Shipment weight
  • cod_amount: Cash on Delivery amount
  • payment_method: Payment method (e.g., "Prepaid", "COD")
  • is_reverse_pickup: Boolean flag for reverse pickup

Dates

  • pickup_date: Date when shipment was picked up
  • received_at: Date when shipment was received at warehouse
  • delivery_date: Date when shipment was delivered

Additional Fields

  • id_customer: Customer ID
  • customer_name: Customer account name
  • tracking_info: Array of status history (see example below)

Complete Example - Delivered Status

{
    "tracking_number": "AY4447538242",
    "reference": "56325059",
    "status": "AY-0005",
    "status_label": "Delivered",
    "reason_code": null,
    "reason_en": null,
    "date_time": "2023-01-08T15:41:26.000000Z",
    "requested_delivery_date": null,
    "delivery_name": "عادل   الخبراني",
    "delivery_email": "[email protected]",
    "delivery_city": "Riyadh",
    "delivery_address": "شارع شارع رابغ، الحي الصحافة ،, عمارتين باللون الأزرق - بجانبها إستراحة,, الرياض, السعودية",
    "delivery_postcode": null,
    "delivery_country": "SA",
    "delivery_phone": "+966551077641",
    "delivery_description": "الأعشاب السبعة (1)",
    "collection_name": "العجائب - ALAJAYEB",
    "collection_email": "[email protected]",
    "collection_city": "Riyadh",
    "collection_address": "Istanbul Street,Al-Sulay District,17889, Riyadh - Al-Sulay District - Istanbul Street, Riyadh,السعودية",
    "collection_neighbourhood": "Al-Sulay District",
    "delivery_neighbourhood": "الصحافة",
    "delivery_date": "2023-01-08T15:41:26.000000Z",
    "is_reverse_pickup": 0,
    "pickup_date": "2023-01-07T11:59:05.000000Z",
    "received_at": "2023-01-07 15:58:18",
    "cod_amount": "0.00",
    "pieces": 1,
    "id_customer": 2167,
    "weight": "0.494",
    "payment_method": "Prepaid",
    "customer_name": "ALAJAYEB",
    "tracking_info": [
        {
            "status_code": "AY-0005",
            "description": "Shipment is delivered to customer - Received by عادل   الخبراني",
            "description_ar": "تم توصيل الشحنة - Received by عادل   الخبراني",
            "created_at": "2023-01-08 18:41:26"
        },
        {
            "status_code": "AY-0004",
            "description": "Shipment is out for its final destination.",
            "description_ar": "الشحنة خارجة للتوصيل للوجة النهائية",
            "created_at": "2023-01-08 12:51:08"
        },
        {
            "status_code": "AY-0026",
            "description": "Received at Riyadh Warehouse",
            "description_ar": "Received at Riyadh Warehouse",
            "created_at": "2023-01-07 15:58:18"
        },
        {
            "status_code": "AY-0003",
            "description": "Shipment is received at hub",
            "description_ar": "أستلمت الشحنة في مركز التوزيع",
            "created_at": "2023-01-07 15:58:18"
        },
        {
            "status_code": "AY-0002",
            "description": "Shipment was collected from collection point",
            "description_ar": "تم إستلام الشحنة من الشركة الشاحنة",
            "created_at": "2023-01-07 14:59:05"
        },
        {
            "status_code": "AY-0001",
            "description": "Shipment is created at collection point",
            "description_ar": "تم إصدار بوليصة شحن لدى الشركة الشاحنة لكن لم تستلم من قبل \"أي مكان \"",
            "created_at": "2023-01-07 13:52:24"
        }
    ]
}

Complete Example - Pending Status

{
    "tracking_number": "AY4335935224",
    "reference": "56148320",
    "status": "AY-0032",
    "status_label": "Pending",
    "reason_code": "AY-0048",
    "reason_en": "Future Delivery",
    "date_time": "2023-01-09T06:17:34.000000Z",
    "requested_delivery_date": null,
    "delivery_name": "سلطان الحربي",
    "delivery_email": "[email protected]",
    "delivery_city": "Riyadh",
    "delivery_address": "شارع خليفة بن حمد، الحي الجنادرية ،, حي الشروق الجنادربة,, الرياض, السعودية",
    "delivery_postcode": null,
    "delivery_country": "SA",
    "delivery_phone": "+966533792102",
    "delivery_description": "الأعشاب السبعة (1)",
    "collection_name": "العجائب - ALAJAYEB",
    "collection_email": "[email protected]",
    "collection_city": "Riyadh",
    "collection_address": "Istanbul Street,Al-Sulay District,17889, Riyadh - Al-Sulay District - Istanbul Street, Riyadh,السعودية",
    "collection_neighbourhood": "Al-Sulay District",
    "delivery_neighbourhood": "الجنادرية",
    "delivery_date": null,
    "is_reverse_pickup": 0,
    "pickup_date": "2023-01-07T11:59:06.000000Z",
    "received_at": "2023-01-07 15:58:16",
    "cod_amount": "177.98",
    "pieces": 1,
    "id_customer": 2167,
    "weight": "0.494",
    "payment_method": null,
    "customer_name": "ALAJAYEB",
    "tracking_info": [
        {
            "status_code": "AY-0032",
            "description": "Shipment is pending - Future Delivery",
            "description_ar": "الشحنة معلقة - مؤجل",
            "created_at": "2023-01-09 09:17:34"
        },
        {
            "status_code": "AY-0026",
            "description": "Received at Riyadh Warehouse - Delayed",
            "description_ar": "Received at Riyadh Warehouse - تأجيل",
            "created_at": "2023-01-08 23:43:05"
        },
        {
            "status_code": "AY-0006",
            "description": "Shipment was not delivered. - shipment delivery was delayed by customer",
            "description_ar": "تمت المحاولة لتوصيل الشحنة ، لم يتم توصيل الشحنة - تم تأجيل موعد إستلام الشحنة من قبل العميل",
            "created_at": "2023-01-08 22:07:26"
        },
        {
            "status_code": "AY-0004",
            "description": "Shipment is out for its final destination.",
            "description_ar": "الشحنة خارجة للتوصيل للوجة النهائية",
            "created_at": "2023-01-08 12:36:31"
        },
        {
            "status_code": "AY-0026",
            "description": "Received at Riyadh Warehouse",
            "description_ar": "Received at Riyadh Warehouse",
            "created_at": "2023-01-07 15:58:16"
        },
        {
            "status_code": "AY-0003",
            "description": "Shipment is received at hub",
            "description_ar": "أستلمت الشحنة في مركز التوزيع",
            "created_at": "2023-01-07 15:58:16"
        },
        {
            "status_code": "AY-0002",
            "description": "Shipment was collected from collection point",
            "description_ar": "تم إستلام الشحنة من الشركة الشاحنة",
            "created_at": "2023-01-07 14:59:06"
        },
        {
            "status_code": "AY-0001",
            "description": "Shipment is created at collection point",
            "description_ar": "تم إصدار بوليصة شحن لدى الشركة الشاحنة لكن لم تستلم من قبل \"أي مكان \"",
            "created_at": "2023-01-07 08:49:44"
        }
    ]
}

{warning} The Webhook URL endpoint must be implemented by customers to receive and process webhook notifications.

Webhook Tester

You can test your webhook through our Webhook Tester to verify the response and check if your webhook integration is working properly.

You will need to enter the Webhook url,Tracking Number,Reference Number,Status(Shipment status) , if the shipment status is Not Delivered you will be required to select a reason as to why the shipment wasn't delivered.

{info} All inputs are required.

Success Response

A success message will say Data sent successfully.

Error Response

In case of an error, the following response can be returned. Error: Request failed with status code 404 meaning that the webhook url is not found.