Webhooks

Requires an Integrations license.

The webhook functionality is available in a basic or advanced option. For more explanation of Webhooks please see this article.

Basic Webhook

Small JSON payload to advise that an event has occurred with an order or route stop.

Sends information in JSON format
Limited information to send over (see examples Basic Webhooks Examples)
Triggered by customer status events

Advanced Webhook

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 Setup & Configuration Advanced Webhook Setup for configuration options)
Triggered by customer status events
GPS updates can be set up to send on a recurring schedule

All times are in UTC ISO 8601 format (see https://en.wikipedia.org/wiki/ISO_8601 ).

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)

See example here for fields and descriptions.

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

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

See example here for fields and descriptions.

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	Description	Data Type
orderId	The internal id of the order	Decimal in 19.2 format
eventType	The event that generated the output (one of the events listed above)	String
eventTimeStamp	The date time of the event	UTC date time

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

See example here for fields and descriptions.

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	Description	Data Type
orderId	The internal id of the order	Decimal in 19.2 format.
eventType	The event that generated the output (only ADDRESSCHANGED)	String
eventTimeStamp	The date time of event	UTC date time
OriginName	Origin name	String - 50 character maximum
OriginAddress	Origin address	String - 50 character maximum
OriginAddress2	Origin address line 2	String - 50 character maximum
OriginCity	Origin city	String - 50 character maximum
OriginState	Origin state	String - 2 character maximum
OriginZip	Origin zip	String - 5 character maximum
OriginPlus4	Origin plus4	String - 4 character maximum
DestName	Destination name	String - 50 character maximum
DestAddress	Destination address	String - 50 character maximum
DestAddress2	Destination address line 2	String - 50 character maximum
DestCity	Destination city	String - 50 character maximum
DestState	Destination state	String - 2 character maximum
DestZip	Destination zip	String - 5 character maximum
DestPlus4	Destination plus4	String - 4 character maximum

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)

See example here for fields and descriptions.

Events: COMPLETED, ARRIVED, SIGNATURE, POD

JSON

{
    "pkId": 12345,
	"eventType": "COMPLETED",
	"eventTimeStamp": "2022-05-26T02:59:17Z",
	"statusInfo": {
		"arrived": "2022-05-26T02:44:25Z",
		"completed": "2022-05-26T02:58:39Z",
		"pod": "J Smith"
	}
}

List of Items

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

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

See example here for fields and descriptions.

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

JSON

{
    "pkId": 12345,
	"eventType": "ACTIVATED",
	"eventTimeStamp": "2022-05-26T02:42:05Z""
}

List of Items

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

You can download examples below.

Event Descriptions

Event	Description
Delivered	On Demand order has been delivered to the destination location
PickedUp	On Demand order has been picked up from the origin location
AtDelivery	Driver has arrived at the destination location
AtPickup	Driver has arrived at the origin location
Placed	On Demand order has been created
Confirmed	On Demand order has been marked as confirmed by the driver assigned to the order
DeliverySignature	A signature has been collected by the driver at the destination location
ReceivedAtDock	On Demand order has been marked as received at dock
StatusUpdate	A status update has been requested/triggered for an On Demand order by a user to provide the latest status details of the order
Canceled	On Demand order has been canceled
Consolidated	On Demand order being placed has been consolidated/merged onto an already existing order
Invoiced	On Demand order has been invoiced
DriverAssigned	On Demand order has been assigned to a driver
DriverUnassigned	The driver assigned to the On Demand order has been removed from the order
RateChanged	The rate on the On Demand order has been changed
StatusCodeAdded	A status code has been added to the On Demand Order
StatusCodeUpdated	An existing status code has been updated on the On Demand order
ParcelExceptionAdded	An exception has been added to a parcel that is assigned to the On Demand Order
NextDelivery	The On Demand order has been marked as the next delivery to take place
NextPickup	The On Demand order has been marked as the next pickup to take place
VerifiedForBilling	The On Demand order have been marked as verified for billing
RejectedByDriver	The On Demand order has been rejected by the assigned driver
AddressChange	The On Demand order had an address changed for either the origin or the destination
Completed	The route stop has been marked as completed
Arrived	The driver has arrived at the route stop location
Signature	A signature has been collected for the route stop
POD	A POD has been collected for the route stop
Activated	The route stop has been activated
AssignedToDriver	The route stop has been assigned to a driver
Consolidated	The route stop being created has been consolidated/merged onto an already existing stop
Created	Route Stop has been created
Deactivated	Route stop has been deactivated
ParcelExceptionAdded	An exception has been added to a parcel linked to the route stop
StatusCodeAdded	A status code has been added to the route stop
StatusCodeUpdated	An existing status code has been updated on the route stop
UnassignedFromDriver	The driver assigned to the route stop has been removed

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 definitions
- URL - Enter the URL to send the webhook messages to

See X Stream Definitions.

For advanced webhooks see Advanced Webhook Setup below for more setup options.

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 a full list of available commands...

Orders

	EXEC spWebHooksProcessEvent @ORDERID=[OrderID], @TYPE='ONDEMAND', @EVENT='ADDRESSCHANGED'
	EXEC spWebHooksProcessEvent @ORDERID=[OrderID], @TYPE='ONDEMAND', @EVENT='ATDELIVERY'
	EXEC spWebHooksProcessEvent @ORDERID=[OrderID], @TYPE='ONDEMAND', @EVENT='ATPICKUP'
	EXEC spWebHooksProcessEvent @ORDERID=[OrderID], @TYPE='ONDEMAND', @EVENT='CANCELED'
	EXEC spWebHooksProcessEvent @ORDERID=[OrderID], @TYPE='ONDEMAND', @EVENT='CONFIRMED'
	EXEC spWebHooksProcessEvent @ORDERID=[OrderID], @TYPE='ONDEMAND', @EVENT='CONSOLIDATED'
	EXEC spWebHooksProcessEvent @ORDERID=[OrderID], @TYPE='ONDEMAND', @EVENT='DELIVERED'
	EXEC spWebHooksProcessEvent @ORDERID=[OrderID], @TYPE='ONDEMAND', @EVENT='DELIVERYSIGNATURE'
	EXEC spWebHooksProcessEvent @ORDERID=[OrderID], @TYPE='ONDEMAND', @EVENT='DISPATCHED'
	EXEC spWebHooksProcessEvent @ORDERID=[OrderID], @TYPE='ONDEMAND', @EVENT='DRIVERASSIGNED'
	EXEC spWebHooksProcessEvent @ORDERID=[OrderID], @TYPE='ONDEMAND', @EVENT='DRIVERUNASSIGNED'
	EXEC spWebHooksProcessEvent @ORDERID=[OrderID], @TYPE='ONDEMAND', @EVENT='INVOICED'
	EXEC spWebHooksProcessEvent @ORDERID=[OrderID], @TYPE='ONDEMAND', @EVENT='NEXTDELIVERY'
	EXEC spWebHooksProcessEvent @ORDERID=[OrderID], @TYPE='ONDEMAND', @EVENT='NEXTPICKUP'
	EXEC spWebHooksProcessEvent @ORDERID=[OrderID], @TYPE='ONDEMAND', @EVENT='PARCELEXCEPTIONADDED'
	EXEC spWebHooksProcessEvent @ORDERID=[OrderID], @TYPE='ONDEMAND', @EVENT='PICKEDUP'
	EXEC spWebHooksProcessEvent @ORDERID=[OrderID], @TYPE='ONDEMAND', @EVENT='PLACED'
	EXEC spWebHooksProcessEvent @ORDERID=[OrderID], @TYPE='ONDEMAND', @EVENT='RATECHANGED'
	EXEC spWebHooksProcessEvent @ORDERID=[OrderID], @TYPE='ONDEMAND', @EVENT='RECEIVEDATDOCK'
	EXEC spWebHooksProcessEvent @ORDERID=[OrderID], @TYPE='ONDEMAND', @EVENT='REJECTEDBYDRIVER'
	EXEC spWebHooksProcessEvent @ORDERID=[OrderID], @TYPE='ONDEMAND', @EVENT='STATUSCODEADDED'
	EXEC spWebHooksProcessEvent @ORDERID=[OrderID], @TYPE='ONDEMAND', @EVENT='STATUSCODEUPDATD'
	EXEC spWebHooksProcessEvent @ORDERID=[OrderID], @TYPE='ONDEMAND', @EVENT='STATUSUPDATE'
	EXEC spWebHooksProcessEvent @ORDERID=[OrderID], @TYPE='ONDEMAND', @EVENT='VERIFIEDFORBILLING'

Route Stops

	EXEC spWebHooksProcessEvent @ORDERID=[PKID], @TYPE='ROUTED', @EVENT='COMPLETED'
	EXEC spWebHooksProcessEvent @ORDERID=[PKID], @TYPE='ROUTED', @EVENT='ARRIVED'
	EXEC spWebHooksProcessEvent @ORDERID=[PKID], @TYPE='ROUTED', @EVENT='SIGNATURE'
	EXEC spWebHooksProcessEvent @ORDERID=[PKID], @TYPE='ROUTED', @EVENT='POD'
	EXEC spWebHooksProcessEvent @ORDERID=[PKID], @TYPE='ROUTED', @EVENT='ACTIVATED'
	EXEC spWebHooksProcessEvent @ORDERID=[PKID], @TYPE='ROUTED', @EVENT='ASSIGNEDTODRIVER'
	EXEC spWebHooksProcessEvent @ORDERID=[PKID], @TYPE='ROUTED', @EVENT='CONSOLIDATED'
	EXEC spWebHooksProcessEvent @ORDERID=[PKID], @TYPE='ROUTED', @EVENT='CREATED'
	EXEC spWebHooksProcessEvent @ORDERID=[PKID], @TYPE='ROUTED', @EVENT='DEACTIVATED'
	EXEC spWebHooksProcessEvent @ORDERID=[PKID], @TYPE='ROUTED', @EVENT='PARCELEXCEPTIONADDED'
	EXEC spWebHooksProcessEvent @ORDERID=[PKID], @TYPE='ROUTED', @EVENT='STATUSCODEADDED'
	EXEC spWebHooksProcessEvent @ORDERID=[PKID], @TYPE='ROUTED', @EVENT='STATUSCODEUPDATED'
	EXEC spWebHooksProcessEvent @ORDERID=[PKID], @TYPE='ROUTED', @EVENT='UNASSIGNEDFROMDRIVER'

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 Setup

This requires CXT Software to set up. Please contact Technical Support by creating a ticket here.

With advanced webhooks, additional key/value pairs can be set up to control the process and content.

Optional Settings

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)
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 These values should not be changed unless required by the destination system. For further information on these settings, please refer to https://restsharp.dev/api/RestSharp.html#class-restclient