Generic API Notification Integration

For orders that you have submitted to the Kornit^X 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 Kornit^X 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.

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.

CODE

{
   "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"
}

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.

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 are sent as standard for all orders where a status callback URL has been provided. However, the Kornit^X 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 Kornit^X 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.

Passive - Selecting this option will send order updates such as status changes every 30 minutes.
Active - Active will send a notification any time there is a change or update made to an order.
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.

Verifying the HMAC Header Value

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:

Hash: sha256
Message: Request body (on a single line with no spaces)
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 Kornit^X 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.

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.

Proxy - You can optionally add the IP address of a proxy server here.

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]. An example of this is provided below.

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