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.

  • Customer Area (Add / Update webhook)
  • APIs (Add / Update / Get)

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 header key for authenticating webhook requests to your endpoint.
  • Authorization Value (Optional): Custom header value that will be sent with the authorization key.

{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 included in the webhook payload sent to your endpoint for verification purposes.

Request

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

  • Content-Type: application/json
  • Accept: application/json

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)

Authorization Fields (Optional)

  • authorization_key: Custom authorization key (if configured)
  • authorization_value: Custom authorization value (if configured)

{info} The authorization fields are only included if you have configured them in your webhook settings.

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.