Webhooks

Owned by Michelle Cabaya (Unlicensed)
May 13, 2022
6 min read

Requirements

  • Integrations license

  • X Dispatch 21.1 or newer or X Dispatch 20.0 to 21.0 with Integration version 1.0.0

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 details 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 webhook functionality is available in a basic or advanced option.

Basic Webhook

A basic webhook sends a pre-determined set of basic data from your system to a third-party system 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 order, the content of the message may not provide sufficient 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, current timestamp, and any date/time stamps for that job (if captured by the driver at the time of transmission)

  • For additional order status events (such as canceled, invoiced, driver assigned, status code added, etc.), basic data includes the order ID, event type, and current timestamp

  • For address change status events, basic data includes the order ID, current timestamp, and address information

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

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

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.

Functionality

Basic Webhook

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

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 Processing below for configuration options)

  • Triggered by customer status events

  • GPS updates can be set up to send on a recurring schedule

Setup & Configuration

X Stream Definition

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

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

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.

  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'

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.

  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.

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

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