How to use Webhooks?

Overview

Webhooks allow you to receive real-time HTTP notifications about changes in specific objects. The full value of webhooks is that you get updates as soon as they have occurred. For example, we can send you a notification right after the order has been updated or the route has been started. This prevents you from having to constantly request the API for changes in objects and helps you to avoid reaching your rate limit.

What’s a Webhook?

A webhook is a message sent by TrackPOD to an app's webhook endpoint. It contains JSON data and metadata in its request body. The included data payload differs depending on a particular event type.

A webhook endpoint is a persisted data object created using the UI settings page. It represents a subscription to the events that your app wants to receive and a destination where the Track-POD app should send webhooks. When an event occurs, the webhook subscription sends a relevant payload to the specified destination.

Setting up webhooks

Webhooks management link can be found on the Web API settings page:

Setting up webhooks is quite simple - it's just a two-step process:

1.   Specify the endpoint URL

   Please note that only HTTPS is supported

   
   2. Select the event type (you can find all types of events at the end of the article)
   

   
   

   

   
   

   After that, you will see the created webhook endpoint page.

   
   

   
   

   Additionally to the displayed webhook endpoint details, this page allows you to:

   
   
   

   • Reveal the signing secret / Create a new one

   
   

   • Disable / Enable the webhook endpoint

   
   

   • Test it by sending sample payload for the selected event type

   
   

   • See all attempts for the last 15 days

   
   

   • Retry failed attempts

   
   
   

   Anatomy of a webhook

   
   

   After creating an endpoint, Track-POD sends an HTTP POST request to the specified endpoint every time an event occurs.

   
   

   The request body contains JSON data that has two sections: Metadata and Data.

   
   

   In the first section, you can find the type of event and the date of its creation. As Track-POD cannot guarantee delivery of events in the order they are generated, so you will have to handle this based on the Date value.

   
   

   See an example of a request body:

   
   

   {
         "Metadata":{
           "Event":"OrderUpdated",
           "Date":"2021-06-26T07:56:53.3197234Z"
         },
         "Data":{
           "Id": "10000345",
           "Number": "000019",
           "Date": "2021-06-25T00:00:00",
           "SeqNumber": 152151251,
           "RouteNumber": "R000123",
           "RouteDate": "2021-06-25T00:00:00",
           "RoutePriority": 10,
           "RouteStatus": "InProgress",
           "DriverLogin": "ds45",
           "DriverName": "John Doe",
           "Type": 0,
           "ShipperId": "345",
           "Shipper": "Track POD",
           "DepotId": "443",
           "Depot": "4400 Shellmound St, Emeryville, CA 94608, USA",
           "ClientId": "245",
           "Client": "ACME",
           "AddressId": "162",
           "Address": "189 Doe Anex, Berkeley, CA 94720, USA",
           "AddressLat": 37.871931,
           "AddressLon": -122.259364,
           "AddressZone": "",
           "TimeSlotFrom": "2021-06-25T09:00:00",
           "TimeSlotTo": "2021-06-25T10:00:00",
           "ServiceTime": 10,
           "Note": "Test update",
           "ContactName": "",
           "Phone": "+15106426000",
           "Email": "[email protected]",
           "Weight": 24.0,
           "Volume": 1.0,
           "Pallets": 3.0,
           "COD": 0.0,
           "CODActual": "0",
           "StatusId": 1,
           "Status": "In Progress",
           "StatusLat": null,
           "StatusLon": null,
           "DriverComment": "Can be late for a 10min",
           "RejectReason": null,
           "SignatureName": null,
           "HasSignaturePhoto": null,
           "SignaturePhotos": null,
           "HasPhoto": null,
           "Photos": null,
           "StatusDate": null,
           "ETA": null,
           "ArrivedDate": null,
           "DepartedDate": null,
           "InvoiceId": null,
           "CustomerReferenceId": null,
           "GoodsList": [
             {
               "OrderLineId": null,
               "GoodsId": "2a768a4a-ceb0-455a-b8a4-1a4b88d702d5",
               "GoodsName": "Books",
               "GoodsUnit": "piece",
               "Note": null,
               "Quantity": 300,
               "QuantityFact": null,
               "Cost": 999.99,
               "RejectReason": null,
               "HasPhoto": false,
               "Photos": null,
               "OrderLineBarcode": null,
               "GoodsBarcode": "6579901",
               "Scanned": false
             }
           ],
           "ReportUrl": null,
           "CustomFields": null,
           "Barcode": null,
           "Scanned": false,
           "FeedbackRating": null,
           "TrackKey": "53316ecf-8ab5-464a-94f6-d304790a3ce8",
           "TrackLink": "https://web.track-pod.com/track?id=53316ecf-8ab5-464a-94f6-d304790a3ce8"
         }
   }

   
   

   Verifying webhooks

   
   

   The request header contains a custom header X-TRACK-POD-TOKEN (see an example with request section below), which holds a secret generated during webhook endpoint creation. Your API should verify if the received value matches the value shown in the webhook endpoint settings to make sure that it was sent by Track-POD.

   
   

   Webhooks retry mechanism

   
   

   When a webhook send fails, the retry mechanism begins. We automatically try to resend the web notification up to 5 times using the exponential backoff strategy as presented below:

   
   
   

   Attempt #	Minutes since the previous attempt
   1	1
   2	5.9
   3	34.81
   4	205.38 (~3 hours)
   5	1211.736 (~20 hours)

   
   

   All attempts are persisted for 15 days, which allows you to see only actual request/response.

   
   

   After 5 unsuccessful attempts, the mechanism stops working, but you can still retry it manually by using the corresponding button in the Webhooks Attemps section.

   
   

   You can do it earlier if the attempt failed but you would like to resend it immediately rather than waiting for the next automatic attempt. If the manual attempt is successful, the scheduled automatic one will be canceled.

   
   

   Supported events and descriptions

   
   

   • Create order

     Is triggered once a new order appears in your account.

     
     

     {
           "Metadata":{
             "Event":"OrderUpdated",
             "Date":"2021-06-26T07:56:53.3197234Z"
           },
           "Data":{
             "Id": "10000345",
             "Number": "000019",
             "Date": "2021-06-25T00:00:00",
             "SeqNumber": 152151251,
             "RouteNumber": "R000123",
             "RouteDate": "2021-06-25T00:00:00",
             "RoutePriority": 10,
             "RouteStatus": "InProgress",
             "DriverLogin": "ds45",
             "DriverName": "John Doe",
             "Type": 0,
             "ShipperId": "345",
             "Shipper": "Track POD",
             "DepotId": "443",
             "Depot": "4400 Shellmound St, Emeryville, CA 94608, USA",
             "ClientId": "245",
             "Client": "ACME",
             "AddressId": "162",
             "Address": "189 Doe Anex, Berkeley, CA 94720, USA",
             "AddressLat": 37.871931,
             "AddressLon": -122.259364,
             "AddressZone": "",
             "TimeSlotFrom": "2021-06-25T09:00:00",
             "TimeSlotTo": "2021-06-25T10:00:00",
             "ServiceTime": 10,
             "Note": "Test update",
             "ContactName": "",
             "Phone": "+15106426000",
             "Email": "[email protected]",
             "Weight": 24.0,
             "Volume": 1.0,
             "Pallets": 3.0,
             "COD": 0.0,
             "CODActual": "0",
             "StatusId": 1,
             "Status": "In Progress",
             "StatusLat": null,
             "StatusLon": null,
             "DriverComment": "Can be late for a 10min",
             "RejectReason": null,
             "SignatureName": null,
             "HasSignaturePhoto": null,
             "SignaturePhotos": null,
             "HasPhoto": null,
             "Photos": null,
             "StatusDate": null,
             "ETA": null,
             "ArrivedDate": null,
             "DepartedDate": null,
             "InvoiceId": null,
             "CustomerReferenceId": null,
             "GoodsList": [
               {
                 "OrderLineId": null,
                 "GoodsId": "2a768a4a-ceb0-455a-b8a4-1a4b88d702d5",
                 "GoodsName": "Books",
                 "GoodsUnit": "piece",
                 "Note": null,
                 "Quantity": 300,
                 "QuantityFact": null,
                 "Cost": 999.99,
                 "RejectReason": null,
                 "HasPhoto": false,
                 "Photos": null,
                 "OrderLineBarcode": null,
                 "GoodsBarcode": "6579901",
                 "Scanned": false
               }
             ],
             "ReportUrl": null,
             "CustomFields": null,
             "Barcode": null,
             "Scanned": false,
             "FeedbackRating": null,
             "TrackKey": "53316ecf-8ab5-464a-94f6-d304790a3ce8",
             "TrackLink": "https://web.track-pod.com/track?id=53316ecf-8ab5-464a-94f6-d304790a3ce8"
           }
     }

     
     For other body examples please visit our API page. Check /Order body for order webhooks and /Route body for route webhooks.

   
   

   • Update order

     This webhook is triggered when order is edited. For instance, a dispatcher changed the order address or goods quantity.

   • Delete order

     This webhook is triggered once an order is deleted.

   • Create route

     Is triggered when a new route appears in your account.

   • Update route

     Is triggered once a route is edited. For instance, a new order is added to the route.

   • Delete route

     Is triggered once a route is removed from your account.

   • Update order status

     This webhook is triggered when order passes from one status to the other. For instance, from In progress to Delivered, or from empty "" status to In progress.

   • Start route

     Once a driver presses the Start route button then this webhook is triggered.

   • Close route

     Once a driver hits the Close route button then this webhook is triggered. 

   • Optimize route

     Is triggered once a route is Optimized by Optimize button from the dashboard or optimize API action (coming soon).

   • Route updated ETA recalculated

     Is triggered once a new updated ETA is generated by the system. This feature is developed to re-calculate ETA according to the driver's position on the route. It updates ETA every 6 minutes taking into account driver's coordinates. Please see this guide for details on updated eta.

   
   

   
   

    IP used for webhooks by Track-POD is 51.68.83.53, 37.59.27.94.