Tutorials // Integrations // How To Setup Webhooks In Detrack

How To Setup Webhooks In Detrack

Webhook is a kind of HTTP callback for sending information to the subsequent systems to integrate with other systems.

This article is regarding the setting up of webhook PUSH notifications to your webhook URL upon a change of job status for your jobs.

Trigger Description
In Transit New job is added, with the primary status set to In Transit.
Info Received New job is added, with the primary status set to Info Received.
Scheduled Occurs when

  • the job status is In Progress
  • has an assigned driver
  • date is of future date
In Progress Occurs when the job status is In Progress.
Heading To Driver tap Head To Location in Driver App.
Partially Completed The job is partially completed, i.e. the job has at least 1 item being rejected in the Item Details.
Failed The job has failed.
Return The job is set to the Returned status.
On Hold The job is set to the On Hold status.
Deleted When the job is Deleted.

To receive the webhook notification, you will need a small web application that can accept the HTTP requests by adding a webhook URL to your application.

Example frameworks of server-side programming languages:

Language Framework
C#
  1. ASP.NET MVC
Java
  1. Servlets
  2. Spark
Node.js
  1. Express
Python
  1. Django
  2. Flask
Ruby
  1. Rails
  2. Sinatra
PHP
  1. Laravel
  2. Symfony
  3. Yii

For more information on the payload of the PUSH notifications, kindly refer to:

  • Version 1: 
    
{
   "date":"2014-02-13",
   "address":"63 Ubi Avenue 1 Singapore 408937",
   "delivery_time":"09:00 AM - 12:00 PM",
   "deliver_to":"John Tan",
   "phone":"+6591234567",
   "notify_email":"john.tan@example.com",
   "notify_url":"http://www.example.com/notify.php",
   "assign_to":"GT1234H",
   "instructions":"Call customer upon arrival.",
   "zone":"East",
   "reason":"",
   "note":"Recipient commented that delivery is very prompt.",
   "received_by":"John",
   "image":1,
   "view_image_url":"https://app.detrack.com/deliveries/photo/52cbaf87f92ea105a4000115.jpg",
   "do":"DO140213001",
   "status":"Delivered",
   "time":"2014-02-13T09:30:45+08:00",
   "pod_lat":1.32502083807714,
   "pod_lng":103.893779271220,
   "pod_address":"63 Ubi Avenue 1, Singapore 408937",
   "items":[
      {
         "sku":"T0201",
         "desc":"Test Item #01",
         "qty":1,
         "reject":0,
         "reason":""
      },
      {
         "sku":"T0202",
         "desc":"Test Item #02",
         "qty":5,
         "reject":0,
         "reason":""
      },
      {
         "sku":"T0203",
         "desc":"Test Item #03",
         "qty":10,
         "reject":0,
         "reason":""
      }
   ]
}
  • Version 2:Detrack V2 API Documentation
    Example PUSH Notification

    {
  "id": "6253e449366df67ff7e75590",
  "type": "Delivery",
  "recipient_sender_device_signature_file_url": null,
  "signature_file_url": null,
  "photo_1_file_url": null,
  "photo_2_file_url": null,
  "photo_3_file_url": null,
  "photo_4_file_url": null,
  "photo_5_file_url": null,
  "photo_6_file_url": null,
  "photo_7_file_url": null,
  "photo_8_file_url": null,
  "photo_9_file_url": null,
  "photo_10_file_url": null,
  "primary_job_status": "dispatched",
  "open_to_marketplace": false,
  "marketplace_offer": null,
  "do_number": "Test1",
  "attempt": 1,
  "date": "2022-04-11",
  "start_date": "2022-04-11",
  "job_age": 1,
  "job_release_time": null,
  "job_time": null,
  "time_window": null,
  "job_received_date": null,
  "tracking_number": null,
  "order_number": null,
  "job_type": null,
  "job_sequence": null,
  "job_fee": null,
  "address_lat": null,
  "address_lng": null,
  "address": "Dummy Address",
  "company_name": null,
  "address_1": null,
  "address_2": null,
  "address_3": null,
  "postal_code": null,
  "city": null,
  "state": null,
  "country": null,
  "billing_address": null,
  "deliver_to_collect_from": null,
  "last_name": null,
  "phone_number": null,
  "sender_phone_number": null,
  "fax_number": null,
  "instructions": null,
  "assign_to": "Adam",
  "notify_email": null,
  "webhook_url": null,
  "zone": null,
  "customer": null,
  "account_number": null,
  "job_owner": null,
  "invoice_number": null,
  "invoice_amount": null,
  "payment_mode": null,
  "payment_amount": null,
  "group_id": null,
  "group_name": null,
  "group_code": null,
  "source": null,
  "weight": null,
  "parcel_width": null,
  "parcel_length": null,
  "parcel_height": null,
  "cubic_meters": null,
  "boxes": null,
  "cartons": null,
  "pieces": null,
  "envelopes": null,
  "pallets": null,
  "bins": null,
  "trays": null,
  "bundles": null,
  "rolls": null,
  "number_of_shipping_labels": null,
  "attachment_url": null,
  "detrack_number": "DET4640992408",
  "status": "dispatched",
  "tracking_status": "Out for delivery",
  "reason": null,
  "received_by_sent_by": null,
  "note": null,
  "carrier": "",
  "pod_time": null,
  "pod_lat": "",
  "pod_lng": "",
  "pod_address": "",
  "address_tracked_at": null,
  "arrived_lat": null,
  "arrived_lng": null,
  "arrived_address": null,
  "arrived_at": null,
  "texted_at": null,
  "called_at": null,
  "serial_number": null,
  "recipient_sender_device_pod_at": null,
  "recipient_sender_device_signed_by": null,
  "signed_at": null,
  "photo_1_at": null,
  "photo_2_at": null,
  "photo_3_at": null,
  "photo_4_at": null,
  "photo_5_at": null,
  "photo_6_at": null,
  "photo_7_at": null,
  "photo_8_at": null,
  "photo_9_at": null,
  "photo_10_at": null,
  "actual_weight": null,
  "temperature": null,
  "hold_time": null,
  "payment_collected": null,
  "auto_reschedule": null,
  "actual_crates": null,
  "actual_pallets": null,
  "actual_utilization": null,
  "goods_service_rating": null,
  "driver_rating": null,
  "customer_feedback": null,
  "eta_time": null,
  "live_eta": null,
  "depot": null,
  "depot_contact": null,
  "department": null,
  "sales_person": null,
  "identification_number": null,
  "bank_prefix": null,
  "run_number": null,
  "head_to_delivery_at": null,
  "pod_at": null,
  "job_price": null,
  "insurance_price": null,
  "insurance_coverage": false,
  "total_price": null,
  "payer_type": null,
  "remarks": null,
  "items_count": 0,
  "service_type": null,
  "warehouse_address": null,
  "destination_time_window": null,
  "door": null,
  "time_zone": null,
  "created_at": "2022-04-11T16:18:18.034+08:00",
  "on_demand": false,
  "vehicle_type": null,
  "priority": null,
  "service_time": null,
  "contractor_group_name": "",
  "connect_token": null,
  "connect_host": null,
  "connect_id": null,
  "verification_code": 3615,
  "locker_address": null,
  "locker_lat": null,
  "locker_lng": null,
  "locker_transaction_id": null,
  "locker_transaction_status": null,
  "locker_station_id": null,
  "locker_error": null,
  "use_locker": false,
  "geofence_ack_at": null,
  "geofence_ack_lat": null,
  "geofence_ack_lng": null,
  "mass_pod": null,
  "pod_gps_status": null,
  "pod_gps_permission": null,
  "job_order": null,
  "tracking_status_code": "dispatched",
  "driver_mobile_number": "123456789",
  "reattempted": null,
  "cubic_meter": null,
  "tracking_link": "https://trk.la/JAJddop",
  "contactless_signature_link": "https://trk.la/JAJddop?s=1",
  "booking_link": "https://trk.la/JAJddop?b=1",
  "can_reattempt": false,
  "items": [],
  "milestones": [
    {
      "status": "out_for_delivery",
      "assign_to": "Adam",
      "reason": null,
      "pod_at": "2022-04-11T16:18:18.032+08:00",
      "created_at": "2022-04-11T16:18:18.034+08:00",
      "user_name": "FrostyDeliveries"
    }
  ]
}

Delivery / Collection

To set up the webhook for both Delivery and Collection jobs.

  1. Navigate to Settings > Webhook.
  2. Enter your Webhook URL for receiving the webhook PUSH notification.
  3. You may select the required triggers (based on job status) to push the information over to the designated URL.

Authentication (Optional)

This section is for users who have authentication setup in their servers for receiving the PUSH notification.

  1. Basic Auth

    1. Select Basic Auth for Webhook Auth Type.
    2. Enter your Username and Password into the Username and Password fields respectively.
  2. Custom Header

    1. Click the Add button to display a table.
    2. Provide the Name and Value.
  3. Click Save when done.

Alternatively, if you wish to separate the webhooks into Delivery and Collection jobs, you may enter the Webhook URL separately under Settings > Delivery or Collection.

  1. Navigate to Settings > Delivery / Collection.
  2. Click on the Webhook URL tab.
  3. Enter the Webhook URL into the field.

Checking Of Webhook Status And Re-Posting

  1. For checking of webhook status, navigate to Settings > Job > Fields.
  2. Enable the Webhook URL field.
  3. Click Save when done.
  4. Create a dummy job.
  5. Click the icon under the Webhook Status column to open a pop-up.
  6. You may refer to the various HTTP statuses for troubleshooting, and re-post the PUSH notification by clicking on the icon under the Repost column.

HTTP Status Codes

HTTP Status Code Description
2xx OK.
3xx Redirect.
4xx Client Error Response.
5xx Server Error Response.

Related Article

  1. Zapier Integration – Catching Hooks from Detrack x Google Sheet
Back to all tutorials