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.
There are two possible ways to setup webhooks for an account.
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 two options to setup.
Webhook URL. It should be always POST.{warning} AyMakan is only responsible for calling the provided Web Hook URL. Security of that URL should be handled by your end.
When calling the Webhook URL, aymakan sends the following data.
Not Delivered (AY-0006) OR Pending (AY-0032), a reason code will be sent in this field. If status is different, then this field will be empty. Reasons codes are basically the status codes and can be found in the statuses list.aymakan.A sample request is as below:
{
"tracking": "AY488",
"reference": "12345",
"status": "AY-0003",
"description": "Received at Warehouse",
"reason": "",
"reason_description": ""
}Example response for Delivered status is as below:
{
"tracking": "AY4447538242",
"reference": "56325059",
"status": "AY-0005",
"description": "Delivered",
"reason": "",
"reason_description": "",
"carrier": "aymakan",
"date_time": "2023-01-08T15:41:26.000000Z",
"shipping": {
"tracking_number": "AY4558538242",
"reference": "56192059",
"status": "AY-0005",
"status_label": "Delivered",
"reason_en": null,
"reason_code": 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,السعودية",
"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",
"collection_neighbourhood": "Al-Sulay District",
"delivery_neighbourhood": "الصحافة",
"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"
}
]
}
}Example response for Pending status is as below:
{
"tracking": "AY4335935224",
"reference": "56148320",
"status": "AY-0032",
"description": "Pending",
"reason": "AY-0048",
"reason_description": "Future Delivery",
"carrier": "aymakan",
"date_time": "2023-01-09T06:17:34.000000Z",
"shipping": {
"tracking_number": "AY4556935224",
"reference": "56148320",
"status": "AY-0032",
"status_label": "Pending",
"reason_en": "Future Delivery",
"reason_code": "AY-0048",
"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,السعودية",
"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",
"collection_neighbourhood": "Al-Sulay District",
"delivery_neighbourhood": "الجنادرية",
"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 is implemented by our customers themselves based on the above details and request data.
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.
A success message will say Data sent successfully.
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.