Notification Integration | Generic API

Notification Integration | Generic API

Introduction

Kornit X has built a notification integration to connect to a Generic API. This notifications integration will alert the customers whenever an order has been received, dispatched and delivered.

Integration Setup

For orders that you have submitted to the KornitX API, you will likely want to receive updates on the status of these orders as they progress through to dispatch. This information can in turn be used to keep your customers updated on the progress of their orders.

The order API provides a "Status Callback URL" field for retailers and brands to attach a status callback URL to each order that they send. Each time the status of the order is updated in the KornitX platform, information about the status update is sent to the callback URL provided with the order. A HTTP PUT request is made to the callback URL and the order status update data is provided in JSON format.

Your status callback should return a 200 HTTP response code if successful. In the event of a 4XX or 5XX error response code, Kornit X will keep retrying the request up to a maximum of 5 times at 2 hour intervals. For statuses that you are not interested in, please be sure to still reply with a 200 response code to prevent unnecessary retries.
Notes
Don't forget that the API may have split your order if it needed to be fulfilled by multiple fulfillers. It's your responsibility to consolidate the status callbacks.
An example of the data that is pushed to the status callback URL when an order status is updated, can be viewed below.

Info
{
   "id":46140204,
   "ref":"8679131463FC8D18",
   "external_ref":"3165671600-PSTEST4",
   "shipping_tracking":"H023YA0000361469",
   "status":8,
   "status_name":"Dispatched",
   "shipping_method":"Courier",
   "shipping_carrier":"Hermes",
   "shipping_price":0,
   "new_shipments":[
      {
         "dispatch_datetime":"2023-02-27 12:04:19",
         "tracking":"H023YA0000361469",
         "tracking_url":"https://www.url.com/123456",
         "items":[
            {
               "quantity":1,
               "ref":"C3DD35B0E1F",
               "external_ref":"10094507"
            }
         ]
      }
   ],
   "new_cancellations":[
      
   ],
   "required_dispatch_date":"2023-02-27"
}

Shipping

The shipping_carrier and shipping_method values may be different to what was specified during order creation. It is common for the values of both fields to mapped to different but equivalent values that the fulfiller is able to accept.
Notes
For example, if Standard Delivery Next Day is specified as the shipping_method during order creation, it may be mapped to Royal Mail and RM1 for shipping_carrier and shipping_method by the fulfiller.

Status Callbacks

Status callbacks are sent as standard for all orders where a status callback URL has been provided. However, the KornitX platform offers an enhanced version of the status callback mechanism, in the form of the Generic API notification integration. The integration offers a choice of HMAC and OpenID Connect Authentication, providing an added layer of security.

To enable the integration for your sales channel, go to Settings>Companies in the KornitX platform and filter to your sales channel companies. Click on the relevant sales channel and select the Notification Integrations tab on the left. From the list of notification integrations, select Generic API. The integration options are described in the following sections.

Enabled - Toggles whether the integration is enabled or disabled.
Start Timestamp (UTC) - The start timestamp of the integration. The integration will only push status updates for orders created after this time.
Order Provider Mode - There are 3 options here. Passive, Active and Entity Events.
  1. Passive - Selecting this option will send order updates such as status changes every 30 minutes.
  2. Active - Active will send a notification any time there is a change or update made to an order.
  3. Entity Events - This option will look for any changes to an independent element within the order, without changes to the order status. An example of this could be an update to the tracking URL element of the order shipment.
Auth Type - There are 2 options here. HMAC and OpenID Connect.

HMAC Authentication

To use HMAC Authentication select HMAC from the Auth Type drop down. If you select HMAC as the authentication method, each request that’s made to the callback URL will include a "X-CustomGateway-Hmac" header. The value of this header can be used to verify the authenticity of the request.

So you can verify the integrity of the callback data being sent using HMAC, we will send you a header with the request named "X-CustomGateway-Hmac".

The value of this is calculated using the following:
  1. Hash: sha256
  2. Message: Request body (on a single line with no spaces)
  3. Secret: The company API key
If the HMAC you calculate matches the value of the "X-CustomGateway-Hmac" header, you can verify that the request is coming from KornitX and that the data hasn't been tampered with during transit (i.e. due to a man in the middle attack).

OpenID Connect Authentication

OpenID Connect is a simple identity layer on top of the OAuth 2.0 protocol. It allows Clients to verify the identity of the End-User based on the authentication performed by an Authorization Server, as well as to obtain basic profile information about the End-User in an interoperable and REST-like manner.

To use OpenID Connect authentication, select OpenID Connect from the Auth Type drop down and fill out the Token URL, Username and Password fields.

  1. Callback URL - The endpoint that the order status update requests will be directed to. If left blank, the callback URL will be taken from the "status_callback_url" field of each order.
  2. Proxy - You can optionally add the IP address of a proxy server here.
  3. DNS Override - This works in a similar way to a hosts file on your operating system, allowing you to direct requests for a given domain and port to a specific IP address. For example, during testing, you may want to direct the requests away from your production environment, to a staging environment. The format of the entries should be [DOMAIN]:[PORT_NUMBER]:[IP_ADDRESS].
Notes
An example of this is provided here: example.com:443:127.0.0.1 - This means direct requests made to example.com on port 443 to the IP address 127.0.0.1

    • Related Articles

    • Notification Integration | Generic Filesystem

      Introduction This article has been created to show how to setup the Notification Integration that Kornit X has built to connect to a Generic Filesystem Setup To setup the Generic Filesystem Notification integration, please head to your company and ...

    • Notification Integration | AfterShip

      Introduction Kornit X has built a notification integration with the third party software AfterShip which sends automated shipment tracking to customers in an aim to increase brand loyalty and driving sales. For more information on AfterShip, please ...

    • Notification Integration | Reviews.io

      Introduction This article has been created to show how to setup the Notification Integration that Kornit X has built to connect to Reviews.io.  Setup To setup the Reviewss.io Notification integration, please head to your company and within the ...

    • Product Integration | Generic API

      Introduction This article has been created to show how to setup the Product integration Kornit X has built to connect to Generic API.  Setup To setup the Generic API integration, please head to your category and within and within the advanced ...

    • Shipper Integration | Generic Label

      Introduction This article has been created to show how to setup the Shipping Integration that Kornit X has built to connect to a Generic Label. Setup To setup the Generic Label integration, please head to your company and within the advanced settings ...