Webhooks
FourKites offers a suite of callbacks (also referred to as "webhooks") that can deliver real-time data to a subscribed API. Typically, it is best to outline which data points your organization may be interested in consuming first, then select which specific messages may best match those data points.
Please note that FourKites' Standard Webhooks is a licensed solution.
Would you be interested in acquiring the Standard Webhooks license? Request a demo by filling out the below form:
Each callback acts as an application event for which a customer’s URL is subscribed. When a customer requests to be subscribed to callback events, a real-time JSON payload will be sent in an HTTP POST to the customer endpoint when that event(s) occurs. As such, any customer who wishes to receive real-time events must define an API endpoint which FourKites can store.
Note: If you have purchased the Network Visibility product and are interested in how to consume events from those loads, please visit the Network Visibility Callbacks folder for payload samples, field definitions, and event triggers
Authentication and Subscriptions
FourKites supports 3 types of authentication on callbacks:
- Basic
- API Key / Auth Header (using keys or secrets inside HTTP headers)
- Oauth2 (client_credentials flow)
The following information needs to be supplied to FourKites in order to subscribe an API to FourKites callbacks:
Field | Description |
|---|---|
URL | URL of the API listening to FourKites callbacks |
Callback Message(s) | Specific messages which you'd like to subscribe to |
Authentication Method | Authentication method used for the callback configuration. Supported options include: • Basic Auth • API Key / Auth Header • Oauth2 (*see oauth2 section below) |
Additional Headers | Any additional headers which may need to be passed in the request |
If using oauth2, FourKites will need to know the token URL, client_id, and client_secret associated with the oauth2 service. Additionally, the token must be presented in a JSON key with the name access_token
Which Callbacks to Use?
Refer to the below visual for the recommended callbacks to receive the most detail from the FourKites platform. Within this table is a mention of which modes each message corresponds to along with other high-level information. For field-level specifications, please visit each message individually in the sections on the left pane.
IP Ranges
FourKites does have a static range of IP addresses which you can whitelist to restrict traffic to your API. If you are interested in obtaining the ranges for both FourKites staging and production, please ask your FourKites Implementation Manager or Customer Success Manager so they may supply the list.
Responses and Retries
While FourKites does not actively monitor success/failure of HTTP responses from customer endpoints, it is recommended that customers have monitors in place to log the success/failure of requests received from FourKites. If assistance is needed regarding callback questions, please submit a ticket with FourKites support.
In the case of 5XX code responses (e.g. an external service is unavailable), FourKites will retry the transaction(s) with an exponential back-off:
- 1 minute
- 15 minutes
- 1 hour
- 24 hours
For any 4XX code responses, retries will not be applied from FourKites.