Fetch Additional Tracking details via Webhooks

This document illustrates the detailed steps on how additional tracking details can be captured by configuring a separate webhook endpoint

Suggest Edits

Overview

Currently, along with the standard tracking scan data, we also receive a set of additional tracking data which is needed by the enterprises. Each piece of additional information necessitates a distinct process for its utilization. Consequently, it has become imperative to establish an efficient procedure for addressing these specific details without incorporating them into our existing webhook setup. To address this challenge, we are initiating the development of a new webhook, dedicated exclusively to conveying these supplementary details to our customers through a webhook payload.

Additional data points in the current scope

We are currently capturing the following information within our system:

OTP Verification: This feature is employed to determine whether a delivered shipment has undergone verification through the use of a One-Time Password (OTP) mechanism. It aids in ensuring the security and authenticity of the delivery process.

Recipient Details:

  • receiver_name: Name of the recipient of the shipment.
  • receiver_id_proof_type: Type of identification document presented by the receiver.
  • receiver_id_proof_number: Identification number on the receiver's provided ID document.
  • receiver_relation: The relationship between the receiver and the sender or the shipment.
  • latitude: Geographic latitude coordinate for the delivered location
  • longitude: Geographic longitude coordinate for the delivered location

FE Details: Contact Name/ Number details of the assigned Field Executive

QC images: Array which contains all the QC images shared during the return pickup

Payload details for the Webhook API

Attached herewith is the webhook payload containing additional details, which are intended to be shared with our customers.

{
	"waybill": "SF49245NER",
	"cp_id": 4,
	"account_code": "delhivery_test",
	"shipment_id": 1233,
	"clickpost_status_description": "Delivered",	
	"clickpost_status_code": 8,
	"latest_timestamp": "2022-10-271T11:52:36+04:00",
	"event": "latitude",
	"delivery_details": {
		"receiver_name": "test",
		"received_relation": "self",
		"received_id": "pan",
		"latitude": 77.0,
		"longitude": 79.0,
		"otp_verified_delivery": True
	},
	"fe_details": {
		"fe_name": "test1",
		"fe_phone": 9100000000
	}
	"qc_images":[
		"sample1",
		"sample2"
	]
}

Here's a field description for the provided JSON data:

  • waybill: The unique identifier for the shipment.
  • cp_id: The identification code for the courier partner.
  • account_code: The account code associated with the courier partner.
  • shipment_id: The identifier for the specific shipment.
  • clickpost_status_description: The textual description of the shipment's Clickpost status (e.g., "Delivered").
  • clickpost_status_code: The numerical code representing the Clickpost status (e.g., 8 for "Delivered").
  • latest_timestamp: The date and time of the latest event (e.g. Delivered Date).
  • event: The field whose value has been updated(exhaustive values: delivery_details, fe_details).
  • delivery_details:
    • receiver_name: The name of the recipient.
    • received_relation: The relationship of the recipient to the sender.
    • received_id: The type of identification received (e.g., PAN card).
    • latitude: Geographic latitude coordinate of the delivery location.
    • longitude: Geographic longitude coordinate of the delivery location.
    • otp_verified_delivery: Indicates whether the delivery was OTP verified (True/False).
  • fe_details:
    • fe_name: The name of the field executive (FE) responsible for the delivery.
    • fe_phone: The contact number of the field executive.
  • qc_images
    • contains an array of items with the QC images shared during the return pickup

List of integrated Courier Partners

  1. Bluedart:
    1. otp_verified_delivery
    2. receiver details
  2. Delhivery
    1. otp_verified_delivery
    2. receiver details
  3. EcomExpress
    1. otp_verified_delivery
  4. Ekart
    1. fe_details
    2. qc_images
  5. Xpressbees
    1. qc_images
  6. Shadowfax
    1. qc_images

PFB the respective webhook payloads that ClickPost receives from the above courier partners to capture the aforementioned data points:

{
	"statustracking": [{
		"Shipment": {
			"SenderID": "Bluedart",
			"ReceiverID": "CLICKPOST",
			"WaybillNo": "31788528306",
			"Origin": "NEW DELHI",
			"OriginAreaCode": "DEL",
			"Destination": "DOMBIVALI",
			"DestinationAreaCode": "DOM",
			"PickUpDate": "23-06-2023",
			"PickUpTime": "2250",
			"ShipmentMode": "F",
			"ExpectedDeliveryDate": "26-06-2023",
			"Feature": "",
			"RefNo": "338860PRAM1742023000",
			"Prodcode": "D",
			"SubProductCode": "",
			"Weight": "0.5",
			"DynamicExpectedDeliveryDate": "26-06-2023",
			"CustomerCode": "301070",
			"Scans": {
				"ScanDetail": [{
					"Scan": "SHIPMENT DELIVERED",
					"ScanCode": "000",
					"ScanGroupType": "T",
					"ScanDate": "26-06-2023",
					"ScanTime": "1112",
					"ScannedLocation": "DOMBIVALI",
					"ScanType": "DL",
					"Comments": "",
					"ScannedLocationCode": "DOM",
					"ScannedLocationCity": "DOMBIVALI",
					"ScannedLocationStateCode": "MH",
					"StatusTimeZone": "IST",
					"StatusLatitude": "",
					"StatusLongitude": "73.0904054",
					"SorryCardNumber": "",
					"ReachedDestinationLocation": "Y",
					"SecureCode": ""
				}],
				"DeliveryDetails": {
					"IDNumber": "5111",
					"IDType": "AC",
					"ReceivedBy": "BHARAT SHARMA",
					"Relation": "SELF",
					"SecurityCodeDelivery": "N",
					"Signature": "",
					"IDImage": ""
				},
				"PODDCImages": {
					"PODImage": [],
					"DCImage": []
				},
				"QC": {
					"Questions": [{
						"item_id": "",
						"question_id": "",
						"description": "",
						"question_value": "",
						"expected_ans": "",
						"actual_ans": ""
					}],
					"Remarks": "",
					"Pictures": [],
					"Result": ""
				},
				"Reweigh": {
					"MPSNumber": "",
					"RWActualWeight": "",
					"RWLength": "",
					"RWBreadth": "",
					"RWHeight": "",
					"RWVolWeight": ""
				},
				"RWImage": [{
					"MPSNumber": "",
					"RWImageURL": ""
				}],
				"FieldExecutiveDetails": {
					"FeName": "",
					"FeMobileNo": "",
					"Feactivity": ""
				},
				"CallLogs": {
					"Message": "",
					"LogDate": None,
					"LogTime": ""
				}
			}
		}
	}]
}

{
	"Shipment": {
		"AWB": "15908511643165",
		"ReferenceNo": "293267NARE2222023000",
		"OrderType": "Pre-paid",
		"PickUpDate": "2023-08-10T17:13:46",
		"ExpectedDeliveryDate": "2023-08-13T23:59:59",
		"Sortcode": "ALW/RAR",
		"NSLCode": "EOD-38",
		"Status": {
			"Status": "Delivered",
			"StatusDateTime": "2023-08-12T11:19:04.002000",
			"StatusType": "DL",
			"StatusLocation": "RajgarhRJ_KarothRd_D (Rajasthan)",
			"Instructions": "Delivered to consignee"
		},
		"OtpValidation": True,
		"ReceiverName": "NARESH KUMAR SAINI",
		"ReceiverIdProofType": "Aadhar Card",
		"ReceiverIdProofNumber": "4566",
		"ReceiverRelation": "NA",
		"Latitude": "0",
		"Longitude": "0"
	}
}

{
	"awb": "3186182012",
	"datetime": "2023-07-15 07:27:59",
	"status": "DELIVERED",
	"reason_code": "Delivered",
	"reason_code_number": "999",
	"location": "GOOTY",
	"Employee": "SHAIK MAHABOOB BASHA",
	"status_update_number": "491031398",
	"order_number": "37800346",
	"city": "GOOTY",
	"ref_awb": "",
	"remarks": "DELIVERED",
	"product_type": "ppd",
	"edd": "2023-07-15",
	"Otp_status": "SKIPPED",
	"Otp_type": "Cancellation OTP"
}

Onboarding steps for the Enterprises to consume the Additional Webhooks

Prerequisites: Ensure that the courier partner webhooks are enabled for tracking all the shipments of any enterprise

Step 1: Ensure that the courier partners for which the additional data points need to be captured are pushing the relevant tracking payload to the ClickPost system (for the exact payload refer to the previous section)

Step 2: The enterprise to expose an endpoint with the following webhook payload to the enterprise for configuration. They should set up an API endpoint and generate an x-api-key to share with us. The generated webhook will be sent to this endpoint

curl -L -X POST 'https://qa-api.qanew.net/wauth/logistics-3p-communicator/api/v1/clickpost/webhook/additional-info' -H 'accept: application/json' -H 'x-api-key: keyvalue' -H 'Content-Type: application/json' --data-raw '{ "waybill": "SF49245NER", "cp_id": 4, "account_code": "delhivery_test", "shipment_id": 1233, "clickpost_status_description": "Delivered", "clickpost_status_code": 8, "latest_timestamp": "2022-10-271T11:52:36+04:00", "event": "latitude", "delivery_details": { "receiver_name": "test", "received_relation": "self", "received_id": "pan", "latitude": 77.0, "longitude": 79.0, "otp_verified_delivery": true }, "fe_details": { "fe_name": "test1", "fe_phone": 9100000000 } }'

Step 3: Share the endpoint with ClickPost Support team along with the additional data points that need to be captured in the tracking data from the respective courier partners

Step 4: Once the webhook integrations are tested and start flowing to the defined endpoint, for every update, the enterprise can refer to the "event" key defined in the request payload. "event" will define the object that has been updated and needs to be modified in the server.

Updated 4 months ago