Build a Shopify app with Ruby and Sinatra

After you have generated an API key and password for your public Shopify application you can start the actual development process.

For this tutorial, you’ll be building your application in Ruby with the official Shopify API gem and the Sinatra framework for Ruby apps.

The sample code for this example app can be found in this GitHub repository. The example app showcases how to subscribe to webhook notifications and update product inventory across multiple product variants for a gift basket product.

Requirements

To follow this tutorial, you will need the following:

Ruby (this example was written with Ruby 2.2.1)
RubyGems, the package management tool for Ruby
Bundler, a Ruby dependency manager
Download the example code from the GitHub repository
To download the necessary dependencies, navigate to the application folder and type bundle install

Step 1: Exposing your application to the Internet

Your application is going to be receiving requests from Shopify, so it needs to be exposed to the Internet. The simplest way to achieve this is through a tunneling service such as ngrok, which will allow you to create a secure tunnel from the public Internet to your local machine.

To initialize ngrok, you’ll need to do the following:

Download ngrok.
In terminal, navigate to the folder where you downloaded ngrok.
If you’re working on OSX or Linux, start ngrok with ./ngrok http 4567. If you’re on Windows, start ngrok with ngrok http 4567.

This will create a tunnel to your local machine on port 4567, which is the default port for Sinatra applications.

Step 2: Configuring your application

Each time you start ngrok, you’ll be assigned a randomly generated subdomain (for example 859998a8.ngrok.io). You will need to configure your application to refer to this address so that Shopify knows where to find your app:

In the sample app code directory, open app.rb and navigate to the beginning of the GiftBasket class.
Change the APP_URL parameter so that it matches the subdomain that you’ve been assigned by ngrok. If you’re not using ngrok, this parameter should match the URL where your application is deployed.
In the folder containing the project code, create a new file named .env and open it in a text editor.

Tip

This example application uses the dotenv Ruby gem to allow you to pull your API_KEY and API_SECRET credentials in from an external file. Your .env file is ignored in GitHub by your .gitignore file, so your credentials will not be visible to humans.
Log in to your Shopify Partner Account.
Click Apps then click the name of your app from the App list.
Click Get API credentials.

Your API Key is displayed under App credentials, and you can click Show beside API secret key to retrieve your API Secret:
Copy the values of the API Key and API Secret from your dashboard, and add them to the .env file in the following format:
```
API_KEY=YOUR_API_KEY
API_SECRET=YOUR_SECRET_KEY
```
Save the .env file and close it.

Configure app URLs

You will also need to configure your application’s URLs.

In your Partner dashboard:

Click Apps.
Click the name of your app.
Click App setup.
For the App URL, type https://#{app_url}/giftbasket/install where app_url is the root path of your application (the same value you have defined in your application as APP_URL).
For Allowed redirection URL(s), type https://#{app_url}/giftbasket/auth.

Step 3: Running your app locally

After configuring your app, you can run the example code locally:

Open a new terminal window.
Navigate into the example code directory.
Type ruby 01\ Getting\ Started/app.rb.

Step 4: Building your application

This section of the tutorial will examine the application code contained in app.rb and explain the rationale for each block of code.

Libraries
Initialization
Installation
Authenticating with Shopify
Creating the webhook subscription
Receiving the webhook notification

Libraries

To start, some useful libraries are included for developing your application:

require 'shopify_api'
require 'sinatra'
require 'httparty'
require 'dotenv'

The Shopify API gem allows you to effortlessly make API calls to Shopify. Sinatra is a lightweight web framework for Ruby that you’ll use to quickly develop your web application. You’ll also be using HTTParty to make HTTP requests. As mentioned before, the dotenv gem will allow you to load environment variables from an external configuration file.

Initialization

At the beginning of the class, some constant values are defined as well as the initialize method.

class GiftBasket < Sinatra::Base
  attr_reader :tokens
  API_KEY = ENV['API_KEY']
  API_SECRET = ENV['API_SECRET']
  APP_URL = "jamie.ngrok.io"

  def initialize
    @tokens = {}
    super
  end

Some constant values are defined to store the application’s API key and secret key, as well as the base URL of the application. (API_KEY, API_SECRET, APP_URL)
The dotenv gem is invoked to import the parameters defined in the .env file that you created.
The application key and secret key are initialized from their respective environment variables.
The empty hash is declared (@tokens), which will be used to store the access tokens granted to the application by Shopify.

Installation

Sinatra uses routes to invoke a particular method when a client sends an HTTP request to the specified address.

get '/giftbasket/install' do
  shop = request.params['shop']
  scopes = "read_orders,read_products,write_products"

  unless /\A[a-zA-Z0-9-]+\.myshopify\.com\z/.match(shop)
    return status 400
  end

  # construct the installation URL and redirect the merchant
  install_url =
    "http://#{shop}/admin/oauth/authorize?client_id=#{API_KEY}&scope=#{scopes}"\
    "&redirect_uri=https://#{APP_URL}/giftbasket/auth"

  redirect install_url
end

The first route defined in the application, /giftbasket/install, is used to define the address where the merchant is redirected to when they click Get in the Shopify App Store. This is the address that you defined earlier as the Application URL in the application settings of your partner dashboard.

When the merchant hits this route, you need to redirect them to the application installation screen on Shopify which will look like this:

In the parameters of the install_url, you need to include the following:

The API key of the application.
Permission scopes required for the application (in this case, the application needs permission to read orders, read products, and write products).
The redirect_uri parameter, which is where the merchant will be redirected after they authorize the installation. This should match the URL defined in the partner dashboard as the Redirection URL. In the case, the merchant is redirected to /giftbasket/auth.

Authenticating with Shopify

After the merchant has authorized the installation of your application, you’ll need to authenticate with Shopify using the OAuth protocol. If you’re not familiar with OAuth, please see our documentation on OAuth.

Verify the request

The first step is to verify that the request is indeed coming from Shopify. You will be able to verify this by performing HMAC signature validation.

get '/giftbasket/auth' do
  # extract shop data from request parameters
  shop = request.params['shop']
  code = request.params['code']
  hmac = request.params['hmac']

  # perform hmac validation to determine if the request is coming from Shopify
  h = request.params.reject{|k,_| k == 'hmac'}
  query = URI.escape(h.sort.collect{|k,v| "#{k}=#{v}"}.join('&'))
  digest = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'), API_SECRET, query)

  if not ActiveSupport::SecurityUtils.secure_compare(hmac, digest)
    return [403, "Authentication failed. Digest provided was: #{digest}"]
  end

First, the hmac parameter is removed from the hash. Next, the remaining keys in the hash are sorted lexicographically, and each key and value pair is joined with an ampersand (‘&’). The resulting string is hashed with the SHA256 algorithm using the application’s secret key as the encryption key. The resulting digest is compared against the hmac parameter provided in the request. If the comparison is successful, you can be assured that this is a legitimate request from Shopify.

Get an access token

To make Shopify API calls on a particular shop, you’ll need an access token belonging to that shop.

if @tokens[shop].nil?
  url = "https://#{shop}/admin/oauth/access_token"

  payload = {
    client_id: API_KEY,
    client_secret: API_SECRET,
    code: code}

  response = HTTParty.post(url, body: payload)

To get the access token, send a POST request to https://<shop>/admin/oauth/access_token where shop is the domain of the shop where the application is being installed (for example test-shop.myshopify.com). The body of the POST request will contain the API key for the application, the application secret key, as well as the code provided in the original request parameters.

If the request was formed correctly, you should expect to receive a response with status code 200 (OK). This response will contain the access token that you’ll be able to use to instantiate a session with the particular Shopify store that you are trying to access. For the sake of this example, you’ll be storing your access token in a hash where the key is the shop domain.

  if response.code == 200
    @tokens[shop] = response['access_token']
  else
    return [500, "Something went wrong."]
  end
end

Creating the webhook subscription

After receiving the access token, you can use it to instantiate a session with Shopify. When the session is active, your application can begin making API calls to Shopify.

This example application utilizes Webhooks which allow Shopify to communicate with the application when certain shop events are triggered.

def instantiate_session(shop)
  # now that the token is available, instantiate a session
  session = ShopifyAPI::Session.new(shop, @tokens[shop])
  ShopifyAPI::Base.activate_session(session)
end

def create_order_webhook
  # create webhook for order creation if it doesn't exist
  unless ShopifyAPI::Webhook.find(:all).any?
    webhook = {
      topic: 'orders/create',
      address: "https://#{APP_URL}/giftbasket/webhook/order_create",
      format: 'json'}

    ShopifyAPI::Webhook.create(webhook)
  end
end

In this case, the webhook subscription has the topic orders/create. This means that Shopify will send a POST request to the specified address every time a new order is created on the merchant’s shop.

Receiving and verifying webhooks

When your application receives the POST request to the address you’ve specified, the first thing you need to do is verify that the request is actually from Shopify and not a potential attacker. The HTTP header of every webhook request sent from Shopify contains a HMAC-SHA256 signature generated using the application’s secret key and the data contained in the body of the request. You will need to generate the same signature and compare it against the header value.

post '/giftbasket/webhook/order_create' do
    # inspect hmac value in header and verify webhook
    hmac = request.env['HTTP_X_SHOPIFY_HMAC_SHA256']

    request.body.rewind
    data = request.body.read
    webhook_ok = verify_webhook(hmac, data)

...

Inside the body of the verify_webhook helper function, the SHA256 digest is computed and compared against the digest provided by Shopify in the HTTP_X_SHOPIFY_HMAC_SHA256 header. A value of true or false is returned.

def verify_webhook(hmac, data)
  digest = OpenSSL::Digest.new('sha256')
  calculated_hmac = Base64.encode64(OpenSSL::HMAC.digest(digest, API_SECRET, data)).strip

  ActiveSupport::SecurityUtils.secure_compare(hmac, calculated_hmac)
end

If the comparison was successful, you’ll need to extract the shop name from the request header and look up the access token necessary to activate a session with Shopify.

if webhook_ok
  shop = request.env['HTTP_X_SHOPIFY_SHOP_DOMAIN']
  token = @tokens[shop]

  unless token.nil?
    session = ShopifyAPI::Session.new(shop, token)
    ShopifyAPI::Base.activate_session(session)
  else
    return [403, "You're not authorized to perform this action."]
  end
else
  return [403, "You're not authorized to perform this action."]
end

The body of the request will contain the information about the new order in the form of a JSON-encoded Order resource.

See example JSON output ›

Making API calls

When the webhook request is received, the application performs the following actions:

Inspects the line_items property of each order.
Inspects the variant_id property of each line item and then determines if they contain a metafield property with the key ingredients.
If true, the app considers that product variant to be a gift basket. The value of the metafield contains a comma-separated list of variant_ids that belong to the gift basket product (created by the merchant).
Decrements the inventory quantity for each of those product variants.

json_data = JSON.parse data

line_items = json_data['line_items']

line_items.each do |line_item|
  variant_id = line_item['variant_id']

  variant = ShopifyAPI::Variant.find(variant_id)

  variant.metafields.each do |field|
    if field.key == 'ingredients'
      items = field.value.split(',')

      items.each do |item|
        gift_item = ShopifyAPI::Variant.find(item)
        gift_item.inventory_quantity = gift_item.inventory_quantity - 1
        gift_item.save
      end
    end
  end
end

return [200, "Webhook notification received successfully."]

Building an app with a Shopify app library

If you’re interested in developing a production-quality application for Shopify, then you might find the following libraries useful:

These libraries contains some useful helper functions for developing your application as well as built-in configuration that makes it easy to deploy your application.

In this video tutorial, you can learn how to make a Rails app with the Shopify App library:

Build a Shopify app with Ruby and Sinatra

Build a Shopify app with Ruby and Sinatra

On this page

Build a Shopify app with Ruby and Sinatra

Requirements

Step 1: Exposing your application to the Internet

Step 2: Configuring your application

Configure app URLs

Step 3: Running your app locally

Step 4: Building your application

Libraries

Initialization

Installation

Authenticating with Shopify

Verify the request

Get an access token

Creating the webhook subscription

Receiving and verifying webhooks

Making API calls

Building an app with a Shopify app library