How to use Webhooks?

Created by Tanya Derevyanko, Modified on Mon, 25 Sep 2023 at 03:06 PM by Tanya Derevyanko

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:

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": "john-doe@track-pod.com",
        "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": "john-doe@track-pod.com",
        "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 37.59.27.94.

How to use Webhooks?

Overview

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.

Setting up webhooks

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

Specify the endpoint URL

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:

Verifying webhooks

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:

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.

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.