Configure webhooks

Use webhooks to get real time updates from your Parcelizer account

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": "[phone]",
    "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": "[email protected]",
        "startAddress": "1132 E Hastings St, Vancouver, BC V6A 1S2, Canada",
        "startLat": 49.2806937,
        "startLng": -123.080293,
        "skills": [],
        "phone": "[phone]",
        "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 "[email protected]" 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
routeplan.dispatch	When the user dispatches a route to drivers for the first time.
routeplan.dispatchUpdate	When the user updates a route and dispatches it again.
order.pickup.arrived	When the driver presses the [Arrive] button on a pickup stop.
order.pickup.completed	When the driver presses the [Completed] button on a pickup stop.
order.pickup.failed	When the driver presses the [Failed] button on a pickup stop.
order.delivery.arrived	When the driver presses the [Arrive] button on a delivery stop.
order.delivery.completed	When the driver presses the [Completed] button on a delivery stop.
order.delivery.failed	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 [email protected] and we'll try to support your use case.