Using Webhook

To receive Order status information from Steadfast using Webhooks, Integration partners will provide this information

• Webhook URL

• Webhook Authentication (optional)

In this topic, we will also discuss

• Status frequency

• Status update completion

4.1 Webhook URL

Any server URL that Steadfast will send order status, Order status information will be posted on this webhook URL.

Example: http://www.integration-partner.com/webhook/order-status

Steadfast will send order status data as given below.

Example Response 1

{
    "OrderFound": true,
    "ConsignmentReference": "N10224648",
    "JobNumber": "859033",
    "TripStatus": "Allocated",
    "FullURL": "https://online.toll.com.au/trackandtrace/traceConsignments.do?consignments=N10224648"
}

4.2 Webhook Authentication

The Integration Partner will provide the authentication mechanism. It can be any authentication mechanism like API Key, Basic Authentication, or Bearer Token. Steadfast will use that authentication mechanism for the webhook. Possible authentication mechanism details are as follows

4.2.1 API Key Authentication

The Integration Partner will provide

• API Key Name e.g. X-Transfocus-Api-Key

• API Key Value e.g 39vj07H5VZJlI+x/0r5Bk8QJj4SFrwo2AapHO0bfFyo=

• API Key either to be passed in

  • Header or

  • Query Param

4.2.2 Basic Authentication

If the Integration Partner is using Basic Authentication then provide this information

• Username e.g. demo

• Password e.g p@55w0rd

4.2.3 Bearer Token Authentication

There are two possibilities of Bearer token

• Bearer Token is provided e.g. eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

• A Bearer Token is not provided but the Bearer Token Server URL is provided, Steadfast will initiate the authentication flow and will get the Bearer Token

  • Bearer Token Server URL

  • Bearer Token Username

  • Bearer Token Password

4.3 Status Frequency

Steadfast will receive a bunch of orders from Integration Partners but will send status updates after a specific time interval. Assume a case, where the Integration Partner sends ten (10) orders. In that case, Steadfast will send all status changes at once, when the Middleware time interval is hit. Currently, that time interval is set to 5 minutes. It means Middleware will send multiple status updates at the same time. Status updates are not batched so after each time interval, multiple status updates will pushed to the webhook.

4.4 Status Retry Mechanism

Steadfast will retry two times to send the status update and will call the webhook URL two (2) times. If it does not succeed, it will be marked as failed.

4.5 Status Update Completion

Steadfast will stop sending status updates against an order when a status update has been previously sent to the Integration Partner. It means it will not duplicate a status update.

If a status update against an order is not available at Steadfast, it will not keep sending individual notifications that the status update is not available. If a status update from internal systems is not retrieved, it will try that order next time.

4.6 Process Flow

When an Order is received it is marked as "Not Completed" and its TripStatus is "Booked". Then whenever its status is changed in the system, an updated status is sent to your Webhook URL. We will not send duplicate Order status. When the last status of "Cancelled" or "Ended" is sent, it will be marked as "Completed" and we will stop sending Order status. A short video explains how the process works.

Steadfast Order Status API - Webhook Process Flow