Managing webhooks

The following shows how to subscribe and manage webhooks that listen to changes in your Bootic shop, using the official Ruby API client.
It also shows how to write a simple Ruby-based web app that listens to event notifications.

1. Configure the client.

Read how to configure the Ruby client library to get the library ready.

2. Instantiate the client

The following creates a Bootic client instance for server-to-server scripts.

client = BooticClient.client(:client_credentials, scope: 'admin')

This example uses a client authorized by a shop owner, for example in a Ruby on Rails application.

client = BooticClient.client(:authorized, scope: 'admin', access_token: session[:access_token]) do |new_token|
  session[:access_token] = new_token
end

Subscription management

Load the root resource.

root = client.root

The root resource includes information on your current scope and the shops you own. From there you can navigate to other resources and take actions such as creating orders.

Load the Hub object

The Hub entity has links to create, delete and list webhooks subscriptions.

hub = root.shops.first.hub

Create a subscription

The following will configure your account to send HTTP notifications to a URL of your choice, every time that a new order is placed in your Bootic shop.

subscription = hub.subscribe(
  topic: "orders.udpated.placed",
  url: "https://myapp.com/events",
  auth: {
    type: "basic",
    username: "foo",
    password: "bar"
  }
)
# subscription.status is "pending",
# waiting for your app to cofirm the first request.

Read more about available event topics.

Note that, when first created, the Bootic API will send a verification request to your provided https://myapp.com/events URL.
The app must respond with a status 204 (200 works, too) and a specific HTTP header. Read more about subscription verification.

If subscription is successful, Bootic will now POST JSON data to https://myapp.com/events every time that an order is placed in your shop.

List subscriptions

You can list all subscriptions for your shop with

subscriptions = hub.subscriptions
subscriptions.each do |s|
  puts [s.topic, s.status].join(' ')
end

The subscriptions endpoint returns a paginated results entity. Using the Ruby client you can use full_set to iterate the full list.

subscriptions = hub.subscriptions.full_set
subscriptions.each do |s|
  puts [s.topic, s.status].join(' ')
end

Delete subscription

hub.unsubscribe(id: subscriptions.first.id)

Subscription history

A new subscription allows you to listen to new changes to your data. The subscription history endpoint gives you a list of past events that match the subscription’s topic.

subscription.history.full_set.each do |event|
  puts [event.topic, event.created_on, event.changes].inspect
end

You can query events by date range:

# all events that have happened since this date
subscription.history(created_on_gte: '2018-01-01T10:00:00Z', sort: 'asc')

Or all events since a given event ID

# all events that have happened since this ID
subscription.history(since: 12343, sort: 'asc')

Note that events look the same as webhook notifications, except they don’t have the embedded item entity. They do have item_type, item_id, topic and other attributes that you can use to get your system up to date with Bootic data.

Webhook consumer app

The following is a simple Ruby web app that will listen to webhook notifications sent by Bootic. As per the example above, this application will be listening for events at https://myapp.com/events.

# using the Sinatra gem https://github.com/sinatra/sinatra
require 'sinatra'
require 'json'

post '/events' do
  # parse the incoming JSON request
  payload = JSON.parse(request.body.read)

  # now deal with each topic you're interested in
  case payload['topic']
  # the first request will be the subscription verification.
  # https://api.bootic.net/rels/subscribe#subscription-verification
  # make sure to respond with the right status and header
  when 'activation'
    halt(204, {'X-Hook-Pong' => request.env['HTTP_X_HOOK_PING'].to_s}, '')
  # handle updated products
  # do something with product data
  when 'products.updated'
    do_something payload['_embedded']['item']
  else
    puts "received notification: #{payload['topic']}"
  end

  # make sure to always repond with a status in the successful range
  halt 204, 'Ok'
end

Using Bootic’s Ruby client to handle events

Because webhook notifications comply with Bootic’s hypermedia conventions, you can use the Ruby client gem to wrap notifications so you can treat them like any other API entity.

require 'bootic_client'
# make sure to configure the client with your credentials
# if you also want to make API requests
BooticClient.configure do |c|
  c.client_id = 'xxx'
  c.client_secret = 'zzz'
end

helpers do
  # your client instance
  # see https://api.bootic.net/guides/rails-integration/ for more
  def client
    @client ||= BooticClient.client(:client_credentials, ...etc)
  end
end

post '/events' do
  # parse the incoming JSON request
  payload = JSON.parse(request.body.read)
  # now we wrap the JSON payload in a BooticClient::Entity object
  event = client.from_hash(payload)

  # now event is an API entity
  case event.topic
    # etc
  end

  # make sure to always repond with a status in the successful range
  halt 204, 'Ok'
end

If your client is configured with valid credentials, you can use these enties like any other one, including follwing available links

if event.has?(:item)
  product = event.item
  # let's update the product
  product = product.update_product(price: 1000)
end