Webhook Documentation

Cart Integration

Introduction

When a customer clicks “Add to Cart” Kit Builder passes the basket data (product description, images, price etc) to your e-commerce solution which will create a custom product and return some data (e.g. a link to the product) which is passed to your custom JavaScript callback function which adds the product to the customer’s cart.

Required Steps Overview

Server-side code to create a custom product in your e-commerce solution and return data for Step 3Configure the server-side endpoint URL from Step 1 in Kit BuilderClient-side JavaScript callback function to add the custom product to your customer’s cartConfigure the Kit Builder product with a cart price and a “qty” integer field

Step 1: Server-side code

Kit Builder will send a POST with a JSON body like this to your server:

{

“PublicWebhookId”: “08ba31c3-957a-4b22-84d3-5567c8d9297f”,

“SingleItemCheckout”: {

   “CategoryName”: “Category Name”,

   “DesignName”: “Design Name”,

   “Html”: “[basic HTML with images and form values]”,

   “MainImage”: “[base 64 encoded png (you can disable in advanced settings: kb.cart_integration.webhook_includes_base64_main_image)]”,

  “Name”: “Category Name Product Name Design Name. (x 5)”,  

  “Price”: 239,

   “ProductName”: “Product Name”,

   “Quantity”: 2,

   “TotalWeight”: 3,

   “UnitPrice”: 119.5,

   “UnitWeight”: 1.5,

   “TeamDetails”: {

         “EnterTeams”: true,

         “Files”: null,

         “Sizes”: [

       {

                “CartPrice”: null,

                “Name”: “128cm”,

                “Quantity”: 3,

                “Sku”: “”,

                “TaxExempt”: false

            },

           {

                “CartPrice”: null,

                “Name”: “152cm”,

                “Quantity”: 2,

                “Sku”: “”,

                “TaxExempt”: true

            }

          ],

           “Teams”: [

                {

                    “Name”: “Team name”,

           “Units”: [

                         {

                            “Id”:”90497088-10f1-4972-8339-cfe9aa7dcdc9″,

                            “CartPrice”: null,

                            “Name”: “Name 1”,

                            “Number”: “1”,

                            “Size”: “128cm”,

                            “Sku”: “”,

                            “TaxExempt”: false

                        },

                      

                   ]

                }

             ]

          }

       }

   }

Your code needs to handle this request by creating a product with these details and return any data as JSON you need for step 3, for example a link to your product.

Note: please don’t rely on the “BasketRawValues” property (not shown in example), this is to help debugging and internal use.

This download also contains a nopCommerce theme with the client-side demo code on the homepage.

Step 2: Configure shop webhook endpoint URL

Enter the endpoint URL for Step 1 on the  company page in the Webhook Endpoint URL field. (We’ll supply login information)

e.g. https://www.example.com/impossible-to-guess-webhook-url

Note: make the URL impossible to guess

Step 3: Client-side code

Initiate Kit Builder with a function that receives data from Step 1, the server-side endpoint, and executes code like adding the new product to the customer’s basket.

JavaScript client-side example (nopCommerce)

This can go as close to the <head> tag as possible.

<script>

   document.addEventListener(“KitBuilderLoaded”, function () {

     KitBuilder.init(“#kitBuilder”, {

         // “Buy Now” and “Add to Cart” buttons on customisation page

              customCallbacks: {

                  webhookAddSingleItemToCartCallback: function(data) {

                      var response = JSON.parse(data.content);

                      // todo: add product to cart

                 },

                 webhookBuyNowCallback: function(data) {

            var response = JSON.parse(data.content);

            // todo: add product to cart and jump user to cart

         }

            },

            currencySymbol: “dkk”,

            currencySymbolAfter: “”,

            currencyFraction: 2,

            // currencyRoundToNearest: 100,

            currencyRate: 1,

            cartItemPricingMethod: “AggregatePricing” // or “SimpleTieredPricing” or “TieredPricing”

    });  

  });

</script>

<script src=”https://api.kitbuilder.co.uk/api/Bootstrapper?distributorId= DISTRIBUTOR_ID&key=DISTRIBUTOR_KEY_HERE” async></script>

Put this where you want Kit Builder to appear:

<div id=”kitBuilder”><noscript>The Kit Builder requires JavaScript to be enabled</noscript></div>

Note: if you have the Tiered Prices feature please ask for further documentation.

Step 4: Configure a Kit Builder product

Configure a product with:

A Cart PriceA product field: Type: Integer, Key: “qty” (you can just click “Add Quantity Field”)

It should be all set up now. On Kit Builder on your website click on a product and on the last configuration step click “Add to Cart”. The Kit Builder client code should pass the data to Kit Builder which will in turn POST a request to your server which will create a custom product and pass back a some custom data which Kit Builder will pass to your custom JavaScript function which will add the customer’s item to their cart.

Local Development

Your shop needs to be accessible on the public internet for Kit Builder to send it data. Developers often test their software locally so they may want to expose a port temporarily for the Kit Builder to send data to.

Tunneling Services

localtunnel ngrok PageKite

Visual Studio, IIS Express and ngrok

IIS Express needs some extra configuration.

1. Download ngrok

2. Run Visual Studio as Administrator

3. Open the nopCommerce project with the Kit Builder plugin

4. Run it

5. Run ngrok ngrok localhost:[LOCAL_PORT_NUMBER] and note ngrok’s public domain e.g. http://example.ngrok.com (sign up for a fixed domain)

6. Open %userprofile%DocumentsIISExpressconfigapplicationhost.config (it may be in an alternative account)

7.And add this under <bindings>:

<binding protocol=”http” bindingInformation=”*:[LOCAL_PORT_NUMBER]:[NGROK_DOMAIN]” /> (replacing [LOCAL_PORT_NUMBER] and [NGROK_DOMAIN])

8. Use this ngrok URL in Step 2: Configure shop webhook endpoint URL


Alternative explanations:

Twilio blog Stack

Overflow answer