Tracking Shipment using Webhook

Overview

The enterprise can configure an endpoint URL on Clickpost's dashboard, where Clickpost will send the tracking updates

📘

A webhook is a way for an application to provide other applications with real-time information. It allows one application to send a message or data to another application when a specific event occurs. This enables enterprises to build integrations that can react to events in real time, rather than having to periodically poll for changes.

📘

Polling Frequency for Carrier Partner

Clickpost hits the carrier partner's tracking API every two hours

Usecase

This is a standard API which applies to all MPS (Multi-Piece Shipment) and SPS (Single Piece Shipment) orders

Selected versus All Statues Webhook

The enterprise can configure the URL on Clickpost's dashboard, where Clickpost will send the updated tracking status once Clickpost receives them from the carrier partner

All Statues Webhook: Every time carrier partner updates tracking of the shipment, We will post data to the enterprise's server using the endpoint URL registered while registering for webhooks.

This will trigger status updates for all the scans done by carrier partner for the shipment. Enterprise can opt in for these webhooks using “Webhooks: All Status” on the dashboard. From tech perspective, apply check on clickpost_status_code in latest_status to update the status in your system.

Selected status Webhooks: In case Enterprise wants to receive notifications only for certain events, Clickpost provides functionality for the same.

If Enterprise opts for these webhooks, we add: "notification_event_id" key in the additional object of the payload. This will inform enterprise the current status of shipment.

This will trigger status updates only for selected checkpoints opted by enterprise on the Clickpost dashboard. Enterprise can opt-in for these webhooks using “Webhooks: Selected Status” on the dashboard. From a tech perspective, apply a check on notification_event_id in the webhook object to update the status in your system. The checkpoints available for Selected webhooks are as mentioned on the dashboard.

📘

Note

The enterprise can also specify whether to receive Webhook updates for all statuses or only for certain statuses.

Important Points to be Considered

1. Webhooks do not guarantee the order of data sends to Client servers. latest_status indicates the latest status for the shipment at the time when the webhook is sent. This is sent with all Webhooks.

2. In case of Failed Delivery, Clickpost unified NDR status code and NDR status description is sent in additional

3. Since Webhooks are transactional in nature, To insure minimal API data loss, we have retries in place if we do not get an HTTP 200 response from your server.

4. If you opt for selected events webhook notification, in case clickpost receives multiple notification from carrier partner at the same time, only the latest notification will be sent to you.

5. While consuming the webhooks do not apply strict JSON check in the code as you might have new keys in the payload as we enhance the services.

6. Please make your API end point idempotent, i.e. every time we hit your API with the same input, we should get the same output.

Configuring the Webhook URL (Old Dashboard)

1. Login to the enterprise dashboard.
2. Click the top-right corner where the enterprise name is mentioned.
3. Go to Setting.
4. Click the Notification tab.
5. Note the 2 sub-tabs in the Notification panel:
   a. Webhook: Selected Status: Here enterprise can specify which statuses to receive updates for, and configure URLs and specify credentials.
   b. Webhook: All Status: Here enterprise can configure URLs and specify credentials to receive updates for every status update from the carrier partner.

Configuring the Webhook URL (New Dashboard)

1. Login to the new enterprise dashboard.
2. On the left-hand side pane, click on Settings.
3. Again on the left-hand side pane, click on Notifications and then Webhooks
4. Note the two tabs in the page Selected Status and All Status:
   a. Selected Status: Here enterprise can specify which statuses to receive updates for, and configure URLs and specify credentials.
   b. All Status: Here enterprise can configure URLs and specify credentials to receive updates for every status update from the carrier partner.

Configuring the Webhook URL Authentication

Most enterprise webhook URLs will require some sort of Authentication. Clickpost also provides the facilities for the enterprise to configure the credentials of their webhook URLs, and Clickpost will make a request to the URL with these credentials.

There are 4 types of authentication that can be set up:

Response from Webhook

The enterprise will receive an update from Clickpost's servers on the enterprise's configured URL. The update will contain the following fields:

The additional object may contain the following sub-fields:

The latest_status object can have the following fields:

Sample Webhook Payload to Enterprise API

{
    "additional": {
        "latest_status": {
            "remark": "Shipment is Out for Delivery",
            "clickpost_status_code": 6,
            "reference_number": "WERA-9616974",
            "timestamp": "2019-05-06T10:04:20Z",
            "clickpost_status_bucket_description": "Out for delivery",
            "location": "DEL_GeetaColony",
            "clickpost_status_description": "OutForDelivery",
            "clickpost_status_bucket": 4,
            "status": "OFD"
        },
        "is_rvp": false,
        "carrier_partner_edd": "2020-03-25",
        "order_id":"ABC123",
    },
    "remark": "Shipment is Out for Delivery",
    "clickpost_status_description": "OutForDelivery",
    "timestamp": "2019-05-06T10:04:20Z",
    "location": "DEL_GeetaColony",
    "status": "OFD",
    "cp_id": 9,
    "clickpost_status_code": 6,
    "waybill": "SF49245NER"
}

{
    "status":"When forward shipment is not accepted by end customer",
    "remark":"Failed Delivery",
    "waybill":"XYZABC",
    "location":"Bengaluru_Koramangala_Dc (Karnataka)",
    "timestamp":"2016-07-12T17:12:36Z",
    "clickpost_status_code":9,
    "clickpost_status_description":"FailedDelivery",
    "cp_id":1,
    "additional":{
        "latest_status":{
            "reference_number":"WERA-9616974",
            "clickpost_status_code":9,
            "location":"Bengaluru_Koramangala_Dc (Karnataka)",
            "status":"When forward shipment is not accepted by end customer",
            "clickpost_status_description":"FailedDelivery",
            "timestamp":"2016-07-12T17:12:36Z",
            "remark":"Failed Delivery"
        },
        "ndr_status_code":1,
        "ndr_status_description":"Customer Unavailable",
        "is_rvp":false,
        "courier_partner_edd":null
    }
}

{
    "waybill":"2614010163240",
    "remark":"Customer escalation received",
    "clickpost_status_code":9,
    "status":"Pending",
    "clickpost_status_description":"FailedDelivery",
    "location":"Lucknow_Aliganj (Uttar Pradesh)",
    "timestamp":"2019-05-01T00:55:06Z",
    "cp_id":4,
    "additional":{
        "ndr_status_code":1,
        "ndr_status_description":"Customer unavailable",
        "notification_event_id":4,
        "is_rvp":false,
        "courier_partner_edd":"2020-03-25",
        "order_id":"ABC123",
        "latest_status":{
            "reference_number":"WERA-NMS1908MSO2",
            "remark":"Customer escalation received",
            "clickpost_status_code":9,
            "status":"Pending",
            "location":"Lucknow_Aliganj (Uttar Pradesh)",
            "clickpost_status_bucket_description":"Failed delivery",
            "clickpost_status_description":"FailedDelivery",
            "timestamp":"2019-05-01T00:55:06Z",
            "clickpost_status_bucket":5
        }
    }
}

{
    "status":"Delivered",
    "clickpost_status_code":8,
    "waybill":"12527345",
    "clickpost_status_description":"Delivered",
    "location":"Nayagarh_Durgprsd_D (Orissa)",
    "cp_id":4,
    "remark":"Delivered to consignee",
    "timestamp":"2019-05-06T15:01:00Z",
    "additional":{
        "notification_event_id":5,
        "is_rvp":false,
        "courier_partner_edd":"2020-03-25",
        "order_id":"ABC123",
        "latest_status":{
            "status":"Delivered",
            "reference_number":"WERA-NMS1908MSO2",
            "clickpost_status_bucket_description":"Delivered",
            "clickpost_status_description":"Delivered",
            "clickpost_status_code":8,
            "location":"Nayagarh_Durgprsd_D (Orissa)",
            "clickpost_status_bucket":6,
            "remark":"Delivered to consignee",
            "timestamp":"2019-05-06T15:01:00Z"
        }
    }
}