Every Jumpseller store has the option to communicate with other services or websites whenever an specific event (like an order payment) happens.
These "webhooks" can be used, for example, to update an external invoicing system, CRM service or fire an alert to your employees via IM or SMS.


Contents

  1. Events
  2. Workflow
  3. Verifying Authenticity
  4. PHP Examples
  5. Tools

Events

When a webhook is triggered it will POST a request, containing data in JSON format, to the specified URL.

The following events can trigger a webhook notification:

Order

  • Order Pending - whenever a new order is created
  • Order Paid - whenever an order receives a payment confirmation
  • Order Shipped - whenever an order is shipped to your customer
  • Order Canceled - whenever, either the store admin or a payment gateway, cancels an order
  • Order Updated - whenever an order changes state, this includes: creating, payment, fullfilment (shipping) and cancelation events

Product

  • Product Created - whenever a new product is added to the store
  • Product Updated - whenever any product details are changed, including changes to the product options & variants
  • Product Deleted - whenever a product is removed from the store

Customer

  • Customer Created - whenever a new customer is registered in the store
  • Customer Updated - whenever any customer profile details are changed
  • Customer Deleted - whenever a customer profile is removed from the store

Workflow

  • On every event we will POST a JSON formated message to your URL.
  • For example, if the event was an order created the message would look like:

    {
      "order": {
        "id": 1026,
        "created_at": "2014-03-01T01:43:16+00:00",
        "status": "Pending Payment",
        "currency": "USD",
        "subtotal": 399.0,
        "tax": 0.0,
        "shipping": 50.0,
        "total": 369.2,
        "discount": 79.8,
        "payment_method_name": "Cash Collection",
        "shipping_method_name": "Flat Rate",
        "payment_information": "Pay at your door step",
        "additional_information": "Leave at reception if not home.",
        "customer": {
          "id": "123",
          "email": "test@gmail.com",
          "phone": "123"
        },
        "shipping_address": {
          "name": "John",
          "surname": "Mattos",
          "address": "Colliers Wood",
          "city": "London",
          "postal": "5000",
          "country": "Britain (UK)",
          "region": "London",
          "municipality": "null"
        },
        "billing_address": {
          "name": "John",
          "surname": "Mattos",
          "address": "Nok Ltd",
          "city": "London",
          "postal": "5771",
          "country": "Britain (UK)",
          "region": "London",
          "municipality": "null"
        },
        "products": [{
          "sku": "black",
          "name": "Black",
          "qty": 1,
          "price": 399.0,
          "discount": 79.8,
          "weight": 1.0,
          "image": "https://example.com/image.png",
          "original_product_id": 100
        }],
        "promotions" => [],
        "additional_fields" => []
      }
    }  
    
  • We expect an HTTP response with status code 2xx, otherwise we will retry delivery other 9 times over more than 4 days ( N^4 where N is the retry attempt number, p.e. the third retry is scheduled in 3 * 3 * 3 * 3 = 81 mins and then the fourth in 256mins )

  • After 10 failed attempts to deliver a message we delete the problematic Webhook permanently and automatically notify the Store Admin by email.


Verifying Authenticity

Webhooks can be verified by calculating a digital signature and comparate it with the value sent in the POST headers:

  • Jumpseller-Hmac-Sha256 the validation code your digital signature needs to match.

This header is generated using the stores hooks token, along with the JSON data sent in the request - so that you confirm all the data on the request was not modified.

To verify that the request came from Jumpseller, compute the HMAC digest according to the following algorithm and check if it's the same value on the Jumpseller-Hmac-Sha256 header.

The following simplistic Ruby code (Sinatra) verifies a Jumpseller webhook request:

require 'rubygems'
require 'base64'
require 'openssl'
require 'sinatra'

HOOKS_TOKEN = 'XXXXX' # get your token at Admin Panel > Config > Notifications / Webhooks.

helpers do
  def verify_webhook(data, hmac_header)
    digest  = OpenSSL::Digest.new('sha256')
    hmac = Base64.encode64(OpenSSL::HMAC.digest(digest, HOOKS_TOKEN, data)).strip
    hmac == hmac_header
  end
end

post '/' do
  request.body.rewind
  data = request.body.read
  verified = verify_webhook(data, env["HTTP_JUMPSELLER_HMAC_SHA256"])
  puts "verified? #{verified}" # true or false.
end

We also sent other Jumpseller specific headers, which are helpful if your applications is handling multiple hooks and/or stores:

  • Jumpseller-Store-Code identifies the store code.
  • Jumpseller-Event identifies the event which fired this webhook.

PHP Examples

  • Example: Receiving an Order Paid notification

    $post = file_get_contents('php://input'); //post data is in another format (e.g. JSON, etc.)
    
    file_put_contents("jumpseller_postorder.txt", $post, FILE_APPEND); //store data locally (JSON to a file in this case)
    
  • Parsing the Order Paid notification

    $post_data = file_get_contents("jumpseller_postorder.txt"); //read JSON file
    
    $json_data = json_decode($post_data, true); //Takes a JSON encoded string and converts it into a PHP variable.
    
    echo $json_data['order']['id'];
    
    echo $json_data['order']['customer']['email'];
    

Tools

We recommend using this free services while testing Webhooks:

  • requestb.in to create an URL and display the received POST requests from your store and
  • jsonviewer to inspect JSON data in a human-friendly way.