Web hooks are one way to send automated messages or information to other apps. Parcelizer uses webhooks to notify your application whenever an important event (like a driver completing a stop) happens in your account. They are particularly useful for logging asynchronous events like when a customer’s delivery is completed, a route is dispatched, or when tracking driver activity.
Why use Webhooks?
Suppose you pay your drivers at the end of each day for the number of completed deliveries they made. A webhook between Parcelizer and your payments system is triggered when a delivery is completed (order.delivery.completed). The JSON payload that is sent to your backend looks like this:
{
"eventName": "order.delivery.completed",
"eventData": {
"orderId": "64c3564336d82c1e3c709834"
}
}
Using the orderId field retrieved from the webhook payload, you can now call the Get Order API to find out which driver completed the order and credit his account for payment.
Endpoint GET https://api.parcelizer.com/ex/orders/{orderId}
Headers
Content-Type: application/json
api_key: YOUR_API_KEY (taken from Settings > General Settings)
Response
{
"routePlanType": "VRP",
"orderCode": "PM2GAHZDN9Z",
"orderRef": "PM2GAHZDN9Z",
"requiredSkills": [],
"deliveryDate": "2023-07-29T00:00:00.000Z",
"deliveryTimeStart": "9:00",
"deliveryTimeEnd": "11:00",
"status": "COMPLETED",
"errorDetails": [],
"notes": "weight: / time_window: / door_code:",
"driverNotes": "Delivered safely ",
"packageWas": "Received by Person",
"pickupEta": null,
"pickupStatus": "ASSIGNED",
"deliveryName": "Irma Henry",
"deliveryAddress": "766 Calverhall St, North Vancouver, BC V7L 1X6, Canada",
"deliveryLat": 49.3137055,
"deliveryLng": -123.0513728,
"deliveryPhone": "+6593654527",
"deliveryEta": "22:48",
"deliveryDuration": 15,
"deliveryNotes": "weight: / time_window: / door_code:",
"fields": {},
"pods": [
"https://parcelizer.s3.us-east-1.amazonaws.com/60e5c88f502c618b521d2565/ZRVLfZAJze0wZU2lOc3eQ.jpg"
],
"signature": "https://api.parcelizer.com/ex/orders/64c3564336d82c1e3c709834/signature.jpg",
"logs": [
{
"status": "ASSIGNED",
"notes": "",
"createdAt": "2023-07-28T05:46:59.684Z"
},
{
"status": "DELIVERY_ARRIVED",
"notes": null,
"createdAt": "2023-07-28T05:48:43.063Z"
},
{
"status": "COMPLETED",
"notes": "Received by Person",
"createdAt": "2023-07-28T05:49:42.021Z"
}
],
"company": "60e5c88f502c618b521d2565",
"routePlan": "64c3563136d82c1e3c709802",
"createdAt": "2023-07-28T05:46:43.276Z",
"updatedAt": "2023-07-28T05:49:42.026Z",
"labels": [],
"_id": "64c3564336d82c1e3c709834",
"driver": {
"companies": [
{
"roles": [
"driver"
],
"company": "60e5c88f502c618b521d2565"
}
],
"groups": [],
"partnerNames": [],
"name": "will-yvr",
"email": "delivery.driver@afi.io",
"startAddress": "1132 E Hastings St, Vancouver, BC V6A 1S2, Canada",
"startLat": 49.2806937,
"startLng": -123.080293,
"skills": [],
"phone": "+18077098998",
"color": "00a2b9",
"shiftStart": "08:00",
"shiftEnd": "12:00",
"speed": "NORMAL",
"status": true,
"createdAt": "2021-12-07T07:18:33.880Z",
"updatedAt": "2023-07-28T05:48:34.195Z",
"_id": "61af0ac95c292adbb74829c0"
}
}
Your backend will then parse this data and credit the driver "will-yvr" (taken from the driver.name field with email address "delivery.driver@afi.io" for the completed delivery.
Configuring your Webhook
To get started, head to Settings > Webhook Configuration and enter the url of the endpoint on your app that will listen to webhooks from Parcelizer. You can add an optional description e.g. "This endpoint triggers payments to drivers for completed stops") if you'd like.
Hit [Update] and your webhook is all set up. Create a route plan and start completing some stops to check if the webhook is firing correctly (a tool like ngrok or RequestBin is perfect for setting up a temporary webhook endpoint for testing).
Supported Events
Parcelizer supports the following events with webhooks:
Event Name | Trigger |
| When the user dispatches a route to drivers for the first time. |
| When the user updates a route and dispatches it again. |
| When the driver presses the [Arrive] button on a pickup stop. |
| When the driver presses the [Completed] button on a pickup stop. |
| When the driver presses the [Failed] button on a pickup stop. |
| When the driver presses the [Arrive] button on a delivery stop. |
| When the driver presses the [Completed] button on a delivery stop. |
| When the driver presses the [Failed] button on a delivery stop. |
If there is an event that you need to capture that is not listed here, please reach out to support@parcelizer.com and we'll try to support your use case.