API Documentation

Web Hook API

Webhooks are triggers that cause zubibu to send an HTTP POST request to a given address upon a given event. They're a great way to avoid having to poll zubibu constantly to find out if a new order has been created, paid, etc.

To set up a webhook, just create one with a specific topic, like 'order/created', set an address like http://myshop.example.com/notify_me and zubibu will send you a request upon that event happening.

Currently the following topics are supported:

  • order/created
  • order/paid
  • order/dispatched
  • order/cancelled

Webhook can be sent either in XML or JSON format. Webhook body will be the same as requested by Order API

If the request fails to connect, zubibu will attempt to re-send the webhook using the following backoff logic: 1 minute, 2 minutes, 5 minutes, 22 minutes, 30 minutes, 60 minutes, 120 minutes, and for 240 minutes 11 times after that (up to 48 hours later).

If the address cannot be reached after 48 hours, zubibu will automatically remove the webhook.

Webhooks are signed with a signature generated by taking an SHA1 hex digest of a string formed by concatenating the Shared Key with the raw body of the webhook post.

To verify if webhook has not been malformed just compare X-Zubibu-Signature header with signature generated by your application. 

request.headers['X-Zubibu-Signature'] == Digest::SHA1.hexdigest(SHARED_KEY + request.body.read)

You can find below simple line of code for Ruby on Rails application. You can find your Shared Key in zubibu backend -> settings -> Api Access

Get all Web Hooks

GET /web_hooks.:format

This method requires authentication

Example

$ curl http://api.zubibu.com/v1/web_hooks.xml?api_key=API_KEY

Response

HTTP/1.1 200 OK
<?xml version="1.0" encoding="UTF-8"?>
<web-hooks type="array">
  <web-hook>
    <format>json</format>
    <topic>order/created</topic>
    <url>http://myshop.example.com/notify_me</url>
    <id type="BSON::ObjectId">4e31ca23ab78b45ea4000002</id>
    <updated-at type="datetime">2011-07-28T22:44:19+02:00</updated-at>
    <created-at type="datetime">2011-07-28T22:44:19+02:00</created-at>
  </web-hook>
</web-hooks>

Get a single Web Hook

GET /web_hooks/:web_hook_id.:format

This method requires authentication

Example

$ curl http://api.zubibu.com/v1/web_hooks/4e31ca23ab78b45ea4000002.json?api_key=API_KEY

Response

HTTP/1.1 200 OK
{
  "format": "json",
  "created_at": "2011-07-28T22:44:19+02:00",
  "updated_at": "2011-07-28T22:44:19+02:00",
  "topic": "order/created",
  "url": "http://myshop.example.com/notify_me",
  "id": "4e31ca23ab78b45ea4000002"
}

Create a new Web Hook

POST /web_hooks.:format

This method requires authentication

Available attributes:

  • format
    • json
    • xml
  • topic
    • order/created
    • order/paid
    • order/dispatched
    • order/cancelled

Example

$ curl -X POST -H "Content-Type: application/json" http://api.zubibu.com/v1/web_hooks.json?api_key=API_KEY \
-d '{"format": "json", "topic": "order/created", "url": "http://myshop.example.com/notify_me"}'

Response

HTTP/1.1 201 Created
{
  "format": "json",
  "created_at": "2011-07-28T23:31:15+02:00",
  "updated_at": "2011-07-28T23:31:15+02:00",
  "topic": "order/created",
  "url": "http://myshop.example.com/notify_me",
  "id": "4e31d523ab78b471bb000009"
}

Modify an existing Web Hook

PUT /web_hooks/:web_hook_id.:format

This method requires authentication

Example

$ curl -X PUT -H "Content-Type: application/json" \
http://api.zubibu.com/v1/web_hooks/4e31d523ab78b471bb000009.json?api_key=API_KEY \
-d '{"url": "http://myshop.example.com/notify_me?secret_key=abcd123456"}'

Response

HTTP/1.1 200 OK
{
  "created_at": "2011-07-28T23:31:15+02:00",
  "format": "json",
  "updated_at": "2011-07-29T08:00:04+02:00",
  "url": "http://myshop.example.com/notify_me?secret_key=abcd123456",
  "topic": "order/created",
  "id": "4e31d523ab78b471bb000009"
}

Remove a Web Hook

DELETE web_hooks/:web_hook_id.:format

This method requires authentication

Example

$ curl -X DELETE http://api.zubibu.com/v1/web_hooks/4e31d523ab78b471bb000009.json?api_key=API_KEY

Response

HTTP/1.1 204 No Content