Web Hook

From Spiffy Stores Knowledge Base

Web Hooks are a means for your Spiffy Store to notify some other web site about an event that has happened.

You can create Web Hooks that are called whenever an order is created or paid, and you can use these hooks to perform a wide range of possible functions.

For example, you can use a Web Hook notification to

  • Notify you of a new order using an SMS or pager message
  • Update your accounting system
  • Provide stock updates for your inventory management software
  • Generate fulfillment requests for a drop-shipping service
  • Create and issue license keys for software products
  • Provide online access to your web site for new customers

A Web Hook is created by providing a web address (URL) and optionally an additional data field.

Web Hooks are created from the "Accounts -> Notifications" page.

When a Web Hook is triggered by a new event, it performs an HTTP POST to the specified web address, passing a unique Web Hook Key to identify your Spiffy Store, a copy of the order data in XML format and any additional data field that was specified when the hook was created.

You need to provide a web application at the web address specified that can process the data that has been passed to it. You can write the web application using any standard web language which is capable of processing XML data. For example, Web Hook notification routines can be written in PHP, Ruby on Rails, ASP.Net and so on.

In order to assist store owners who are unable to program their own Web Hooks, we are providing a set of Web Hook applications that will interface with standard services, such as Email Marketing providers. See below for further details.

Once a Web Hook notification has been created, an attempt will be made to process it. If the notification fails because the server or network is unavailable, then the notification will be re-queued and will be retried later on. This process will continue with increasing delays between attempts until the notification is finally delivered or the attempt fails after about 25 days.

Example Web Hook Post

Here is an example of the format of the data that a Web Hook posts to your application. 

POST /your-web-hook-path HTTP/1.1
Accept: */*
Content-Type: application/xml
Content-Length: 2665
X_spiffy_stores_id: 00000000-0000-0000-0000-000000000000
X_spiffy_stores_data: 7e7d30d6669234475f1baac97d33669234

<?xml version="1.0" encoding="UTF-8"?>
<order>
  <buyer-accepts-marketing type="boolean">false</buyer-accepts-marketing>
  <cart-token nil="true"/>
  <closed-at type="datetime" nil="true"></closed-at>
  <created-at type="datetime">2010-06-18T00:00:00+10:00</created-at>
  <currency>AUD</currency>
  <email>spiffy@mystore.spiffystores.com</email>
  <financial-status>paid</financial-status>
  <fulfillment-status>unshipped</fulfillment-status>
  <gateway>Testing Gateway</gateway>
  <id type="integer">0</id>
  <ip>127.0.0.1</ip>
  <note></note>
  <number type="integer">99999</number>
  <shipping-method>Australia Post</shipping-method>
  <shop-id type="integer">0</shop-id>
  <subtotal-price type="decimal">81.82</subtotal-price>
  <taxes-included type="boolean">true</taxes-included>
  <total-discounts type="decimal">10.0</total-discounts>
  <total-line-items-price type="decimal">91.82</total-line-items-price>
  <total-price type="decimal">100.0</total-price>
  <total-shipping type="decimal">50.0</total-shipping>
  <total-tax type="decimal">12.72</total-tax>
  <total-weight type="float">0.2</total-weight>
  <name>#99999</name>
  <billing-address>
    <address1>1 Bill St</address1>
    <address2></address2>
    <city>Billingsworth</city>
    <company></company>
    <country>Australia</country>
    <first-name>Spiffy</first-name>
    <id type="integer"></id>
    <last-name>Customer</last-name>
    <phone></phone>
    <province>New South Wales</province>
    <title>Mr</title>
    <zip>3333</zip>
    <name>Spiffy Customer</name>
  </billing-address>
  <shipping-address>
    <address1>1 Ship St</address1>
    <address2></address2>
    <city>Shipping Town</city>
    <company></company>
    <country>Australia</country>
    <first-name>Spiffy</first-name>
    <id type="integer"></id>
    <last-name>Customer</last-name>
    <phone></phone>
    <province>New South Wales</province>
    <title>Mr</title>
    <zip>2222</zip>
    <name>Spiffy Customer</name>
  </shipping-address>
  <line-items type="array">
    <line-item>
      <fulfillment-service>manual</fulfillment-service>
      <weight type="float">0.1</weight>
      <id type="integer"></id>
      <price type="decimal">25.0</price>
      <quantity type="integer">2</quantity>
      <sku>ITEM001</sku>
      <name>A very wonderful item</name>
    </line-item>
    <line-item>
      <fulfillment-service>manual</fulfillment-service>
      <weight type="float">0.1</weight>
      <id type="integer"></id>
      <price type="decimal">25.0</price>
      <quantity type="integer">2</quantity>
      <sku>ITEM002</sku>
      <name>A Barrel of Monkeys</name>
    </line-item>
  </line-items>
</order>

Adding Security to your Web Hook Application

Spiffy Stores includes a unique Web Hook key in the request header that can be used to validate the request. A unique key is generated for each store.

You can access the key using the request header value 'HTTP_X_SPIFFY_STORES_ID'.

For example, an application written in PHP would validate the key with the following code. 

  define('MY_SPIFFY_KEY', '0c1c9920-5c9c-012d-bd34-000c295ec56b');
  
  // Check for a valid Spiffy Store Web Hook Key
  if (strcmp(MY_SPIFFY_KEY, $_SERVER['HTTP_X_SPIFFY_STORES_ID']) != 0) {
    header('HTTP/1.1 403 Forbidden');
    exit(0);
  }

You can find your unique Web Hook key on the Notifications page, just underneath the list of current notifications.

Accessing Additional Data

You can retrieve any additional data using the request header value 'HTTP_X_SPIFFY_STORES_DATA'.

This additional data is specified when the Web Hook is created.

Return Data

Spiffy Stores will look for a status code between 200 and 399 to determine if the Web Hook notification was successful.

Sample Code

Here is the skeleton of a Web Hook notification routine written in PHP. 

<?php
/*
 * Sample Web Hook Notification Routine
 */

  define('MY_SPIFFY_KEY', '0c1c9920-5c9c-012d-bd34-000c295ec56b');
  
  // Check for a valid Spiffy Store Web Hook Key
  if (strcmp(MY_SPIFFY_KEY, $_SERVER['HTTP_X_SPIFFY_STORES_ID']) != 0) {
    header('HTTP/1.1 403 Forbidden');
    exit(0);
  }

  // Read the XML data
  $xml_str  = '';
  $xml_data = fopen('php://input' , 'rb');

  while (!feof($xml_data)) {
    $xml_str .= fread($xml_data, 4096);
  }

  fclose($xml_data);

  $req_xml = new SimpleXMLElement($xml_str);

  // Check for opt-in
  if(strcasecmp($req_xml->{'buyer-accepts-marketing'}, 'true') != 0) {
    header('HTTP/1.1 200 OK');
    exit(0);
  }

  /* Connect to remote web site API */
  ....

  /* Process Return Code */
  if (false === $result ) {
    header('HTTP/1.1 400 Bad request');
    print 'Error';
  } else {
    header('HTTP/1.1 200 OK');
    print 'Success';
  }

  exit(0);
?>

Predefined Web Hook Applications

MailChimp

You can use the Spiffy Stores MailChimp web hook routine by specifying the following information when creating your Web Hook. 

Web Address: http://spiffyserver.com/apps/mailchimp/LIST_ID
Additional Data: API_KEY

The LIST_ID is optional, and if not provided, the application will use the first list in your MailChimp account.

Note: Do not add the characters LIST_ID in the web address. Use the actual list id from your MailChimp account.

For example, if your LIST_ID is ba8e5beac4, then you would enter 

Web Address: http://spiffyserver.com/apps/mailchimp/ba8e5beac4 (Sample only)

Please login to your MailChimp account to retrieve the values for your API_KEY and LIST_ID. You will need to generate an API_KEY the first time you access your MailChimp account.

You can access your API_KEY by navigating to "Account -> API Keys & Authorized Apps". The API_KEY will look something like this 

e9a74326bb9999999999b1b4e29a5722-us1 (Sample only)

You can find a list's unique LIST_ID by going to the List's Settings and navigating to the bottom of the page. There you will find a unique LIST_ID consisting of a 10 character sequence of numbers and letters.

Campaign Monitor

You can use the Spiffy Stores Campaign Monitor web hook routine by specifying the following information when creating your Web Hook. 

Web Address: http://spiffyserver.com/apps/campaign_monitor/LIST_ID
Additional Data: API_KEY

Please login to your Campaign Monitor account to retrieve the values for your API_KEY and LIST_ID.

To get your API key, log in to your campaign monitor account, and click on "Account settings" at the top of the screen, then click on the link that says "Show API Key". Your API key is then shown You should copy and paste it into the "Additional Data" filed that is shown when you create your web hook.

To get your List ID, click on the "Lists & subscribers" tab in Campaign Monitor, then click on the list name that you want customers to be subscribed to. You then click on the link that says "change name/type". The List ID is displayed under the title "API Subscriber List ID".

Retrieved from "http://www.spiffystores.com.au/kb/index.php?title=Web_Hook&oldid=3446"