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": "[phone]",
        "Email": "[e-mail]",
        "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 payloads

• Create order;
  
  ex.:

{
"Number": "cv30001-2",
"Id": "10000345",
"Date": "2019-02-01T00:00:00",
"SeqNumber": 2,
"RouteNumber": "R000123",
"RouteDate": "2019-02-01T00:00:00",
"RoutePriority": 10,
"RouteStatus": "Draft",
"DriverLogin": "ds45",
"DriverName": "Dilan",
"Type": 0,
"ShipperId": "357",
"Shipper": "Sanitex",
"DepotId": "1",
"Depot": "9 Riverside, Salford M7 1PA ",
"ClientId": "247",
"Client": "Maxima",
"AddressId": "13587",
"Address": "2 St Josephs Crescent, Liverpool L3 3JF",
"AddressLat": 25.29048,
"AddressLon": 65.29405,
"AddressZone": "Zone 1",
"TimeSlotFrom": "2019-02-01T09:00:00",
"TimeSlotTo": "2019-02-01T18:00:00",
"ServiceTime": 10,
"Note": "Only to sign Invoice",
"ContactName": "John Doe",
"Phone": "[phone]",
"Email": "[e-mail]",
"Weight": 50.5,
"Volume": 8.54,
"Pallets": 3.5,
"COD": 20.45,
"CODActual": "20.50",
"StatusId": 3,
"Status": "Delivered",
"StatusLat": 25.29048,
"StatusLon": 65.29405,
"DriverComment": "The customer was angry for being late",
"RejectReason": "Out Of Time",
"SignatureName": "Andrew Bart",
"HasSignaturePhoto": true,
"SignaturePhotos": [
"https://image.track-pod.com/..."
],
"HasPhoto": false,
"Photos": [
"https://image.track-pod.com/..."
],
"StatusDate": "2019-02-01T15:31:00",
"ETA": "2019-02-01T15:27:00",
"ArrivedDate": "2019-02-01T15:25:00",
"DepartedDate": "2019-02-01T15:31:00",
"InvoiceId": "inv0002 ",
"CustomerReferenceId": "ord123/1",
"GoodsList": [
{
"OrderLineId": "22435324",
"GoodsId": "30495",
"GoodsName": "Some big mystic box",
"GoodsUnit": "pcs.",
"Note": "ID3658AAA",
"Quantity": 10.5,
"QuantityFact": 9.5,
"Cost": 2.99,
"RejectReason": "Out Of Time",
"HasPhoto": true,
"Photos": [
"https://image.track-pod.com/..."
],
"OrderLineBarcode": "1234567890123",
"GoodsBarcode": "1234567890123",
"Scanned": false
}
],
"ReportUrl": "Paid feature, please contact support for details",
"CustomFields": [
{
"Id": "cf_123",
"Label": "string",
"Value": "Text Value"
}
],
"Barcode": "1234567890123",
"Scanned": false,
"FeedbackRating": 5,
"TrackKey": "3F2504E0-4F89-11D3-9A0C-0305E82C3301",
"TrackLink": "https://web.track-pod.com/track?id=d8662b19-ece7-4cda-baa3-c711ade5ad15"
}

and others:

• Update order;
• Delete order;
• Create route;
• Update route;
• Delete route;
• Update order status;
• Start route;
• Close route;
• Optimize route.