Webhooks

Requires an Integrations license.

1 Basic Webhook
- 1.1 Examples
2 Setup & Configuration
- 2.1 X Stream Definition
- 2.2 Message Formats
- 2.3 Customer Status Events
3 Advanced Webhook

A webhook (also called a callback or push API) is used to provide other applications with real-time information. In CXT Software’s context, webhooks are used by the Operations App to provide integration/trading partners or other third-party applications with real-time data based on status events such as picked up or delivered. Typical APIs require third-parties to regularly poll your system for updates while webhooks save time and resources by making the constant polling unnecessary. The callbacks will be sent to the defined URL via an HTTP POST request.

The webhook functionality is available in a basic or advanced option.

Basic Webhook

A basic webhook sends a pre-determined set of basic JSON formatted data from your system to a third-party system via HTTP POST when a status event occurs (such as picked up or delivered). For example, this could be sending an update from your system to your trading partner when you’ve completed a pickup or delivery for one of their orders.

Because basic webhooks are used to notify trading partners that an action has been taken on an order, the content of the message may not provide significant detail. Trading partners will likely prefer to request a full order update from the API as a follow up call for more information.

Examples

For primary order status events (such as confirmed, at pickup, picked up, delivered, etc.), basic data includes the order ID, event type, and any date/time stamps for that job (if captured by the driver at the time of transmission)

Events: DELIVERED, PICKEDUP, ATDELIVERY, ATPICKUP, PLACED, CONFIRMED, DELIVERYSIGNATURE, RECEIVEDATDOCK, STATUSUPDATE

JSON

{
    "orderId": 12345.0,
	"eventType": "DELIVERED",
	"eventTimeStamp": "2022-05-26T02:33:02Z",
	"statusInfo": {
		"ordered": "2022-05-26T00:52:00Z",
		"receivedAtDock": "2022-05-26T01:21:00Z",
		"dispatched": "2022-05-26T01:16:00Z",
		"rejectByDriver": "2022-05-26T02:18:00Z",
		"confirmed": "2022-05-26T01:16:00Z",
		"atPickup": "2022-05-26T01:20:00Z",
		"pickedUp": "2022-05-26T01:20:00Z",
		"atDelivery": "2022-05-26T02:18:00Z",
		"delivered": "2022-05-26T02:33:00Z",
		"pod": "J Smith"
	}
}

List of Items

Field Name	Data Type	Description

Field Name	Data Type	Description
orderId	Decimal (19.2)	The internal id of the order
eventType	String	The event that generated the output (one of the events listed above)
eventTimeStamp	Datetime (UTC ISO 8601)	The date time of the event
statusInfo	Object	Additional information as available and returned if the status occurred
ordered	Datetime (UTC ISO 8601)	The ordered date time Always returned
receivedAtDock	Datetime (UTC ISO 8601)	The received at dock date time Only returned if the order has been marked received at dock
dispatched	Datetime (UTC ISO 8601)	The dispatched date time Only returned if the order has been dispatched
rejectByDriver	Datetime (UTC ISO 8601)	The reject by driver date time Only returned if order was rejected by driver
confirmed	Datetime (UTC ISO 8601)	The confirmed date time Only returned if order has been marked as confirmed
atPickup	Datetime (UTC ISO 8601)	The at pickup date time Only returned if the driver has marked the order as “Arrived” at the the pickup location
pickedUp	Datetime (UTC ISO 8601)	The picked up date time Only returned if order has been picked up and marked it as completed
atDelivery	Datetime (UTC ISO 8601)	The at delivery date time Only returned if the driver has marked the order as “Arrived” at the delivery location
delivered	Datetime (UTC ISO 8601)	The delivered date time Only returned if the order has been delivered and marked completed
pod	String (50)	The pod name of the order Only returned if there is a pod name

For additional order status events (such as canceled, invoiced, driver assigned, status code added, etc.), basic data includes the order ID, event type, and date/timestamps for the event

Events: CANCELED, CONSOLIDATED, INVOICED, DRIVERASSIGNED, DRIVERUNASSIGNED, RATECHANGED, STATUSCODEADDED, STATUSCODEUPDATED, PARCELEXCEPTIONADDED, NEXTDELIVERY, NEXTPICKUP, VERIFIEDFORBILLING, REJECTEDBYDRIVER

JSON

{
    "orderId": 12345.0,
	"eventType": "DRIVERASSIGNED",
	"eventTimeStamp": "2022-05-26T01:13:40Z"
}

List of Items

Field Name	Data Type	Description

Field Name	Data Type	Description
orderId	Decimal in (19.2)	The internal id of the order
eventType	String	The event that generated the output (one of the events listed above)
eventTimeStamp	Datetime (UTC ISO 8601)	The date time of the event

For address change status events, basic data includes the order ID, date/timestamp of the event, and address information

Events: ADDRESSCHANGE

JSON

{
    "orderId": 12345.0,
    "eventType": "ADDRESSCHANGED",
    "eventTimeStamp": "2022-05-26T01:36:32Z",
    "OriginName": "Origin Customer",
    "OriginAddress": "800 N 75th Ave",
    "OriginAddress2": "",
    "OriginCity": "Phoenix",
    "OriginState": "AZ",
    "OriginZip": "85043",
    "OriginPlus4": "    ",
    "DestName": "Destination Customer",
    "DestAddress": "135 W Hillview St",
    "DestAddress2": "",
    "DestCity": "Mesa",
    "DestState": "AZ",
    "DestZip": "85201",
    "DestPlus4": "    "
}

List of Items

Field Name	Data Type	Description

Field Name	Data Type	Description
orderId	Decimal (19.2)	The internal id of the order
eventType	String	The event that generated the output (only ADDRESSCHANGED)
eventTimeStamp	Datetime (UTC ISO 8601)	The date time of event
OriginName	String (50)	Origin name
OriginAddress	String (50)	Origin address
OriginAddress2	String (50)	Origin address line 2
OriginCity	String (50)	Origin city
OriginState	String (2)	Origin state
OriginZip	String (5)	Origin zip
OriginPlus4	String (4)	Origin plus4
DestName	String (50)	Destination name
DestAddress	String (50)	Destination address
DestAddress2	String (50)	Destination address line 2
DestCity	String (50)	Destination city
DestState	String (2)	Destination state
DestZip	String (5)	Destination zip
DestPlus4	String (4)	Destination plus4

For primary route stop status events (such as arrived, completed, signature, etc.), basic data includes the route stop ID, event type, and any date/time stamps for that job (if captured by the driver at the time of transmission)

Events: COMPLETED, ARRIVED, SIGNATURE, POD

JSON

List of Items

Field Name	Data Type	Description

Field Name	Data Type	Description
pkid	Integer	The internal id of the route stop
eventType	String	The event that generated the output (one of the events listed above)
eventTimeStamp	Datetime (UTC ISO 8601)	The date time of event
statusInfo		Additional information as available.
arrived	Datetime (UTC ISO 8601)	The arrived date time Only returned if driver has been marked arrived at the route stop
completed	Datetime (UTC ISO 8601)	The completed date time Only returned if route stop has been marked as completed
pod	String (50)	The pod name of the route stop Only returned if there is a pod name

For additional route stop status events (such as consolidated, deactivated, status code added, etc.), basic data includes the route stop ID, event type, and date/timestamp of the event

Events: ACTIVATED, ASSIGNEDTODRIVER, CONSOLIDATED, CREATED, DEACTIVATED, PARCELEXCEPTIONADDED, STATUSCODEADDED, STATUSCODEUPDATED, UNASSIGNEDFROMDRIVER

JSON

List of Items

Field Name	Data Type	Description

Field Name	Data Type	Description
pkId	Integer	The internal id of the route stop
eventType	String	The event that generated the output (one of the events listed above)
eventTimeStamp	Datetime (UTC ISO 8601)	The date time of event

Setup & Configuration

The following setup and configurations are done in the Operations App.

X Stream Definition

The X Stream definition will automate the processing of the webhooks, using message formats and customer status events.

Create an X Stream definition with the following settings.

Configuration Type: WBOUTBOUND
Export Type: Plugin - Plugin
Plugin Export Type: Webhooks
Key Value definition
- URL - Enter the URL to send the webhook messages to

See X Stream Definitions.

URL is the only key value pair required. For advanced webhooks see Optional Settings below for more setup options.

Please contact Technical Support for more information or questions.

Optional Settings

Setting	Description

Setting	Description
Method	Web method to be used (e.g. POST, PUT, PATCH, etc..) (defaults to POST)
ContentType	Content type to be used can be application/XML or application/json (defaults to application/XML)
BodyType	Data type sent back from the stored procedure (NOTE: THIS MUST BE SET TO EITHER JSON OR XML depending on what the stored procedure is returning)
HeaderTag	Tag used to denote header keys (defaults to header_) (NOTE: See below for more information)
DateTimeFormatting	Option that the time values are based on. SERVER (default) LOCALIZE UTC
BatchProcessStoredProcedure	Stored procedure used during batch processing (defaults to spWebHooksBatch)
BatchXsltAttachmentID	XSLT attachment ID used during batch processing (NOTE: See below for more information)
QueueStoredProcedure	Stored procedure used during queue processing (defaults to spWebHooksQueue)
StoredProcedureDataType	Data type returned by stored procedure (either XML or json) (defaults to XML)
ThrowExceptionOnWebCallFail	True/false to enable disable throwing an exception if a web call does not return OK/200 (defaults to false)
RestClientTag	Tag used to denote rest client keys (defaults to restclient_) (NOTE: See below for more information)
SignatureEncoding	Signature format to export (e.g. NONE, BMP, GIF, PNG, JPG, SVG, TIF) (defaults to NONE)
SignatureElement	Data node that contains signature (NOTE: This is post XSLT processing)
Authentication Tags
AuthUrl	Authentication URL
AuthMethod	Authentication web method to be used (e.g. POST, PUT, PATCH, etc..) (defaults to POST)
AuthContentType	Authentication content type to be used (defaults to application/XML)
AuthBody	Authentication body
AuthUsername	Authentication user name. (Sent as part of Authorization Basic header)
AuthPassword	Authentication password. (Sent as part of Authorization Basic header)
AuthAccessTokenNode	Authentication node that returns the token (defaults to token)
AuthExpiresInNode	Authentication node the returns the expires in value (can now be empty if authentication does not return an expires in value - defaults to 0 if not returned)
AuthorizationHeaderToken	what is sent back with authorized calls (defaults to Bearer). This is what is sent in the header of authorized calls (e.g. "Authorization", "Bearer 239203239203kdlad03")
RetryMax	Number of retry attempts (defaults to 0) -- 0 is disabled
RetryDelay	Number of seconds to wait between retries (defaults to 0) -- 0 is disabled
RetryDelta	Number of seconds to increase the delay for each retry (defaults to 0) -- 0 is disabled
Header Tags
HeaderTag	String that will denote header values (defaults to header_) Keys that start with the HeaderTag will be passed as header parameters (e.g. header_apikey - the associated value will be passed as "apikey" request header parameter)
Restclient Tags
RestClientTag	String that will denote rest client parameter (defaults to restclient_) Keys that start with the RestClientTag will be used to configure the rest client. (e.g. restclient_timeout - the associated value will be set used to set the timeout value in the rest client) This is a list of the rest client configuration settings that can be configured: AutomaticDecompression Pipelined FollowRedirects UserAgent Timeout ReadWriteTimeout UseSynchronizationContext PreAuthenticate ThrowOnDeserializationError FailOnDeserializationError ThrowOnAnyError UnsafeAuthenticatedConnectionSharing AllowMultipleDefaultParametersWithSameName

Message Formats

Message formats are used for basic updates to send the message that the webhook was triggered. Advanced webhooks may require additional setup or configuration.

Create the appropriate message formats for the order or route stop that will be used with webhooks. For example, if you want to send picked up and delivered information, create two message formats (one for Order Picked Up and one for Order Delivered).
Check the Execute SQL Statement checkbox in the Advanced tab.
Paste the appropriate SQL commands into the Advanced tab of the message format.
- Example command for a Order Picked Up message format:
  EXEC spWebHooksProcessEvent @ORDERID=[OrderID], @TYPE='ONDEMAND', @EVENT='PICKEDUP'
- Example command for a Order Delivered message format:
  EXEC spWebHooksProcessEvent @ORDERID=[OrderID], @TYPE='ONDEMAND', @EVENT='DELIVERED'

See Message Formats (Classic Operations App) or Message Formats.

Customer Status Events

Status events on the customer record are what will send the message format when the webhook is triggered.

In the customer record, go to the Contacts tab.
In the Alerts section, select the Status Event and the corresponding Message Format you created.
Repeat step 2 as needed.
Save the customer record.

See Customers - New/Edit Customer.

Advanced Webhook

An advanced webhook is similar to a basic webhook, but with customization options for the information included in when a status event occurs. If the pre-determined set of details from the basic webhook does not provide the trading partner with the information they need (or they are not able to make a follow up API call to get more info, and prefer to accept web posts) the details sent via the webhook can be expanded using the advanced webhooks to provide more information in real-time. Any configuration of custom advanced webhooks will require Integration Services assistance to match a requested format.

Customizable JSON/XML payload to provide selected order or route stop information.

Sends information in JSON or XML format
All order and/or route stop fields are available to be sent over (see Optional Settings below)
Triggered by Status Events
GPS updates can be set up to send on a recurring schedule