API Webhook

Webhooks are a useful tool for apps that want to execute code after a specific event happens on a store, for example, after a customer creates a cart on the storefront, or a merchant creates a new product in their admin.

Instead of telling your app to make an API call every X number of minutes to check if a specific event has occurred on a shop, you can register webhooks, which send an HTTP request from the store telling your app that the event has occurred. This uses far less API requests overall, allowing you to build more robust apps, and update your app instantly after a webhook is received.

Webhooks are scoped to the app they're registered to. This means that when a webhook is registered to an app, other apps can't view, modify, or delete it.

Anatomy of a Webhook

When an event occurs in a shop that corresponds to a registered webhook, Spiffy Stores sends a webhook notification to the specified URL. The webhook contains a payload formatted as JSON, as well applicable HTTP headers. For example, the following headers are sent as part of the

orders/create

webhook.

• X-Spiffy-Topic: orders/create
• X-Spiffy-Hmac-Sha256: XWmrwMey6OsLMeiZKwP4FppHH3cmAiiJJAweH5Jo4bM=
• X-Spiffy-Shop-Domain: johns-apparel.spiffystores.com

etc.

Some of the returned HTTP headers can be useful for your app. For example, X-Spiffy-Hmac-Sha256 is used to authenticate webhooks, and X-Spiffy-Shop-Domain is useful for determining the store context. See the webhooks tutorial for more information concerning authenticating webhooks, and the OAuth docs for general information concerning authentication.

List of Supported Webhook Topics

Event data can be stored as JSON or XML. Webhooks can be registered for the following events:

Events	Topics
Cart	carts/create, carts/update { "id": "eeafa272cebfd4b22385bc4b645e762c", "token": "eeafa272cebfd4b22385bc4b645e762c", "line_items": [ { "id": 1234567, "properties": { }, "quantity": 3, "variant_id": 1234567, "key": "1234567:f816dcc3b2e26822a28626a786eac953", "title": "Example T-Shirt - ", "price": "19.99", "original_price": "19.99", "discounted_price": "19.99", "line_price": "59.97", "original_line_price": "59.97", "total_discount": "0.00", "discounts": [ ], "sku": "example-shirt-s", "grams": 200, "vendor": "Acme", "product_id": 327475578523353102, "gift_card": false } ] }
description	{ "description" : "Goods returned from Order #12345" } The description provides reference information on why the credit was issued or redeemed.
customer	{ "customer" : {   "id": 6,   "title": "Mr",   "first_name": "Frodo",   "last_name": "Baggins",   "name": "Mr Frodo Baggins",   "email": "frodo@theshire.com",   "accepts_marketing": true,   "created_at": "2010-06-15T13:15:50Z",   "updated_at": "2015-02-23T03:02:51Z",   "note": "This customer has an interest in rings.",   "orders_count": 512,   "state": "enabled",   "total_spent": "11230.63",   "sign_in_count": 261,   "current_sign_in_at": "2015-02-23T03:02:51Z",   "current_sign_in_ip": "192.168.10.164",   "last_sign_in_at": "2015-02-19T05:58:54Z",   "last_sign_in_ip": "192.168.10.164",   "wholesale": false,   "credit": "0.0",   "tags": "friend,ring_bearer,brave,hobbit" } } Returns an object containing information about the customer. Customer objects contain the following fields: id - A unique numeric identifier for the customer title - The customer's title first_name - The customer's first name last_name - The customer's last name name - The customer's full name, including title email - The customer's email address accepts_marketing - Acceptance of marketing emails created_at - The date and time when the account was created updated_at - The date and time when the account was updated note - Additional information about the customer orders_count - The number of orders placed by the customer state - The current state of the customer's account Valid states are: enabled disabled invited declined total_spent - The total amount spent by the customer sign_in_count - The number of successful sign ins current_sign_in_at - The time of the current sign in current_sign_in_ip - The IP address of current sign in last_sign_in_at - The time of the last sign in last_sign_in_ip - The IP address of the last sign in wholesale - Customer has access to wholesale prices credit - Amount of credit in customer's account tags - Tags associated with customer
order	{ "order" : { Order details… } } Returns an object containing information about the order. The customer credit has an associated order only when a credit is being posted against a specific order. More detailed information about the order can be found at API Order.
created_at	{ "created_at" : "2015-10-24T18:26:31Z" } The date and time when the customer credit was created. The timestamp is in ISO 8601 format.
updated_at	{ "updated_at" : "2016-01-16T05:50:56Z" } The date and time when the customer credit was last updated. The timestamp is in ISO 8601 format.

Further Reference

• An Introduction to the Spiffy Stores API
• Creating Private API Keys
• Using the API
• API Reference