Versions Compared

Old Version 6

changes.mady.by.user Michelle Cabaya

Saved on

compared with

New Version 7

changes.mady.by.user Michelle Cabaya

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Info

Requires an Integrations license.

Table of Contents
minLevel1
maxLevel7

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

Excerpt-include
CXTsupport:Webhooks
CXTsupport:Webhooks
nameBasicWebhook

...

Basic Webhook

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

Excerpt
nameAdvancedWebhook

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

Info

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

...

  • 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)

...

titleSee example here for fields and descriptions.

...

nopaneltrue

Info

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

Anchor
basicexamples
basicexamples
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)

Expand
titleSee example here for fields and descriptions.

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

JSON

Code Block
{
    "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

...

Data Type

...

orderId

Decimal (19.2)

The internal id of the order

...

Decimal in 19.2 format

...

eventType

String

The event that generated the output (one of the events listed above)

...

String

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

...

UTC date time

  • receivedAtDock

Datetime (UTC ISO 8601)

The received at dock date time
Only returned if the order has been marked received at dock

...

UTC date time

...

  • dispatched

Datetime (UTC ISO 8601)

The dispatched date time
Only returned if the order has been dispatched

  • rejectByDriver

...

UTC date time

...

  • confirmed

Datetime (UTC ISO 8601)

The reject by driver date time
Only returned if order was rejected by driver

  • confirmed

...

UTC date time

Datetime (UTC ISO 8601)

The confirmed date time
Only returned if order has been marked as confirmed

...

UTC date time

...

  • atPickup

...

  • pickedUp

  • 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

...

UTC date time

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

...

UTC date time

...

Datetime (UTC ISO 8601)

The delivered date time
Only returned if the order has been delivered and marked completed

...

UTC date time

  • pod

String (50)

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

Expand
titleSee example here for fields and descriptions.

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

JSON

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

List of Items

Field Name

...

Description

...

Data Type

Description

orderId

Decimal in (19.2)

The internal id of the order

...

Decimal in 19.2 format

...

eventType

String

The event that generated the output (one of the events listed above)

...

String

eventTimeStamp

Datetime (UTC ISO 8601)

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

Expand
titleSee example here for fields and descriptions.

Events: ADDRESSCHANGE

JSON

Code Block
{
    "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

orderId

Decimal (19.2)

The internal id of the order

...

Decimal in 19.2 format.

...

eventType

String

The event that generated the output (only ADDRESSCHANGED)

...

String

...

eventTimeStamp

Datetime (UTC ISO 8601)

The date time of event

...

UTC date time

OriginName

String (50)

Origin name

OriginAddress

String

...

(50)

Origin address

OriginAddress2

String

...

(50)

Origin address line 2

OriginCity

String

...

(50)

Origin city

...

String - 50 character maximum

...

OriginState

String (2)

Origin state

...

String - 2 character maximum

OriginZip

String (5)

Origin zip

OriginPlus4

String

...

OriginPlus4

...

(4)

Origin plus4

...

String - 4 character maximum

DestName

String (50)

Destination name

DestAddress

String

...

(50)

Destination address

DestAddress2

String

...

(50)

Destination address line 2

DestCity

String

...

(50

...

)

...

DestCity

Destination city

DestState

String

...

(2)

Destination state

DestZip

String

...

DestZip

(5)

Destination zip

DestPlus4

String

...

DestPlus4

(4)

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)

Expand
titleSee example here for fields and descriptions.

Events: COMPLETED, ARRIVED, SIGNATURE, POD

JSON

Code Block
{
    "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

...

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)

...

String

eventTimeStamp

Datetime (UTC ISO 8601)

The date time of event

...

UTC date time

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

...

UTC date time

...

  • completed

...

Datetime (UTC ISO 8601)

The completed date time
Only returned if route stop has been marked as completed

...

UTC date time

  • pod

String (50)

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

Expand
titleSee example here for fields and descriptions.

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

JSON

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

List of Items

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)

...

String

eventTimeStamp

Datetime (UTC ISO 8601)

The date time of event

...

UTC date time

You can download examples below.

View file
nameWebhooksSamples.zip

Event Descriptions

Customer Level Status 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

Info

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.

Note

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

Image Removed

...

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

  1. 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).

  2. Check the Execute SQL Statement checkbox in the Advanced tab.

  3. 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'

...

titleSee a full list of available commands...

Orders

Code Block
languagesql
	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

Code Block
languagesql
	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.

  1. In the customer record, go to the Contacts tab.

  2. In the Alerts section, select the Status Event and the corresponding Message Format you created.

  3. Repeat step 2 as needed.

  4. Save the customer record.

See Customers - New/Edit Customer.

...

Info

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.

...