Webhooks

Introduction

This resource covers:

What is a webhook?

Webhook is a tool for retrieving and storing data from a certain event. They allow you to register an http:// or https:// URL where the event data can be stored in JSON formats. For Deliveryby apps, webhooks are commonly used for:

  • Placing an order
  • Collecting data for data-warehousing
  • Integrating your accounting software

Think of it this way, if you have  have to poll for a substantial amount of data, you should be using webhooks.


Webhook events

Webhooks can be registered for the following events:

Order
creation
Order
update_status

Configure a webhook

You can set up your webhooks through your store admin.

The issue with testing your webhooks is that you need a public visible URL to handle them. Unlike client-side redirects, webhooks originate directly from the server. This means that you cannot use the following as an endpoint in your testing environment:

  • Localhost
  • "Fake" domains like www.example.com
  • Deliveryby domains (i.e. deliveryby.com)

Configure a webhook through your store admin

If you are developing an app for a particular shop, you can configure your webhooks through your shop admin. Go to the Advanced Settings > Webhooks page.


Select the event type you want to listen for from the drop-down box and enter the URL (http:// or https://) where you want to receive notifications.

After you have created at least one webhook, you will be presented with a secret that you can use to validate the integrity of these webhooks


If you want to capture the contents of a webhook to examine them, the easiest way is to set up a new subscription with a service like LocalTunnel, RequestBin or PostCatcher (described above) which will capture the result and let you view it in a browser.

RequestBin allows you to create an URL wich will collect any requests made to it. You can then inspect your requests and see the values returned. The URL provided is temporary and can only be used for 20 requests or for 48 hours (whichever comes first).


Receive a webhook

Once you register a webhook URL with Deliveryby, we will issue a HTTP POST request to the URL specified every time that event occurs. The request's POST parameters will contain JSON data relevant to the event that triggered the request.


Respond to a webhook

Your webhook acknowledges that it received data with a 200 OK response. Any response outside of the 200 range will let Deliveryby know that you did not receive your webhook. To this end, Deliveryby has implemented a 5-second timeout period and a retry period for subscriptions. We wait 5 seconds for a response to each request, and if there isn't one or we get an error, we retry the connection to a total of 19 times over the next 48 hours. A webhook will be deleted if there are 19 consecutive failures for the exact same webhook.

You should monitor your admin for failing webhooks. If you're receiving a Deliveryby webhook, the most important thing to do is respond quickly. There have been several historical occurrences of apps that do some lengthy processing when they receive a webhook that triggers the timeout. This has led to situations where webhooks were removed from functioning apps.

To make sure that apps don't accidentally run over the timeout limit, we now recommend that apps defer processing until after the response has been sent.


Verify a webhook created through the API

Webhooks created through the API by a Deliveryby App can be verified by calculating a digital signature.

Each Webhook request includes a X-Deliveryby-Hmac-SHA256 header which is generated using the app's shared secret, along with the data sent in the request.

Webhooks created manually through the Deliveryby admin will need to be verified with the secret found within the webhooks section of the notifications area.

To verify that the request came from Deliveryby, compute the HMAC digest according to the following algorithm and compare it to the value in the X-Deliveryby-Hmac-SHA256 header. If they match, you can be sure that the Webhook was sent from Deliveryby and the data has not been compromised.

Note that if you are using a Rack based framework such as Ruby on Rails or Sinatra the header you are looking for is HTTP_X_DELIVERYBY_HMAC_SHA256

Below is a simple example in Ruby using the Sinatra web framework of how one might verify a webhook request.

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




# The Deliveryby app's shared secret, viewable from the Partner dashboard
SHARED_SECRET = 'my_shared_secret'




helpers do
  # Compare the computed HMAC digest based on the shared secret and the request contents
  # to the reported HMAC in the headers
  def verify_webhook(data, hmac_header)
    digest  = OpenSSL::Digest::Digest.new('sha256')
    calculated_hmac = Base64.encode64(OpenSSL::HMAC.digest(digest, SHARED_SECRET, data)).strip
    calculated_hmac == hmac_header
  end
end




# Respond to HTTP POST requests sent to this web service
post '/' do
  request.body.rewind
  data = request.body.read
  verified = verify_webhook(data, env["HTTP_X_DELIVERYBY_HMAC_SHA256"])




  # Output 'true' or 'false'
  puts "Webhook verified: #{verified}"
end

And here's a PHP version:






define('DELIVERYBY_APP_SECRET', 'my_shared_secret');




function verify_webhook($data, $hmac_header)
{
  $calculated_hmac = base64_encode(hash_hmac('sha256', $data, DELIVERYBY_APP_SECRET, true));
  return ($hmac_header == $calculated_hmac);
}








$hmac_header = $_SERVER['HTTP_X_DELIVERYBY_HMAC_SHA256'];
$data = file_get_contents('php://input');
$verified = verify_webhook($data, $hmac_header);
error_log('Webhook verified: '.var_export($verified, true)); //check error.log to see the result




?>

Get your delivery software ©2017