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 several 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.
{info} If you provide authorization credentials, they will be included in the webhook payload sent to your endpoint for verification purposes.
When calling the Webhook URL, AyMakan sends a POST request with the following headers:
application/jsonapplication/jsonThe request body includes comprehensive shipment data:
{info} The authorization fields are only included if you have configured them in your webhook settings.
{
"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"
}
]
}{
"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.
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.