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.

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 Created - when a new order is created
  • Order Paid - when your store receives a payment confirmation
  • Order Shipped - when you ship the order to your customer
  • Order Canceled - when, either you or a payment gateway, cancels an order
  • Order Updated - whenever an order changes state, this includes: creating, payment, fullfilment (shipping) and cancelation events

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":{ "email":"test@gmail.com", "phone":"123"},
    "shipping_address":{ "name":"John", "surname":"Mattos", "address":"Colliers Wood", "city":"London", "postal":"5000", "country":"Britain (UK)", "region":"London"},
    "billing_address":{ "name":"John", "surname":"Mattos", "address":"Nok Ltd", "city":"London", "postal":"5771", "country": "Britain (UK)", "region":"London" },
    "products":[{
      "sku":"black",
      "name":"Black",
      "qty":1,
      "price":399.0,
      "discount":79.8,
      "weight":1.0}]
    }}  
    
  • 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 a webhook

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.