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 store, 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.

If you're not a developer, or you don't have access to any developer skills, don't despair! You might want to look at a service such as Zapier which offers a quick and simple way for you to connect your Spiffy Store to hundreds of other web applications and services.

API Webhooks should not be confused with our older, limited Notification Webhooks. The Notification Webhooks are designed to only provide a simple order notification service, whereas API Webhooks can be registered on a much wider range of events.

Anatomy of a Webhook

When an event occurs in a store 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-Stores-ID: 0c1c9920-5c9c-012d-bd34-000c295ec56b
X-Spiffy-Stores-Topic: orders/create
X-Spiffy-HMAC-SHA256: XWmrwMey6OsLMeiZKwP4FppHH3cmAiiJJAweH5Jo4bM=
X-Spiffy-Stores-Shop-Domain: mynewstore.spiffystores.com
X-Spiffy-Stores-Order-Id: 12345
...

Some of the returned HTTP headers can be useful for your app. For example, X-Spiffy-Stores-HMAC-SHA256 is used to authenticate webhooks, and X-Spiffy-Stores-Shop-Domain is useful for determining the store context.

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 } ] }
Checkout	checkouts/create, checkouts/delete, checkouts/update { "id": 327474488104976385, "token": "123123123", "cart_token": "eeafa272cebfd4b22385bc4b645e762c", "email": "example@email.com", "gateway": null, "buyer_accepts_marketing": false, "created_at": "2017-03-20T16:02:28-04:00", "updated_at": "2017-03-20T16:02:28-04:00", "landing_site": null, "note": null, "note_attributes": [ ], "referring_site": null, "shipping_lines": [ ], "subtotal_price": "398.00", "taxes_included": false, "total_discounts": "0.00", "total_line_items_price": "398.00", "total_price": "398.00", "total_tax": "0.00", "total_weight": 1134, "currency": "USD", "completed_at": null, "closed_at": null, "user_id": null, "location_id": null, "source_identifier": null, "source_url": null, "device_id": null, "line_items": [ { "applied_discounts": [ ], "key": "620af35986d9bf455f434f064144c570", "compare_at_price": null, "destination_location_id": 938998167, "fulfillment_service": "manual", "gift_card": false, "grams": 567, "line_price": "199.00", "origin_location_id": 938998166, "price": "199.00", "product_id": 632910392, "properties": null, "quantity": 1, "requires_shipping": true, "sku": "IPOD2008PINK", "tax_lines": [ ], "taxable": true, "title": "IPod Nano - 8GB", "variant_id": null, "variant_title": "", "vendor": "Apple" }, { "applied_discounts": [ ], "key": "620af35986d9bf455f434f064144c570", "compare_at_price": null, "destination_location_id": 938998167, "fulfillment_service": "manual", "gift_card": false, "grams": 567, "line_price": "199.00", "origin_location_id": 938998166, "price": "199.00", "product_id": 632910392, "properties": null, "quantity": 1, "requires_shipping": true, "sku": "IPOD2008PINK", "tax_lines": [ ], "taxable": true, "title": "IPod Nano - 8GB", "variant_id": null, "variant_title": "", "vendor": "Apple" } ], "name": "#327474488104976385", "source": null, "discount_codes": [ ], "abandoned_checkout_url": "https:\/\/checkout.local\/690933842\/checkouts\/123123123\/recover", "tax_lines": [ ], "source_name": "web", "billing_address": { "first_name": "Bob", "address1": "123 Billing Street", "phone": "555-555-BILL", "city": "Billtown", "zip": "K2P0B0", "province": "Kentucky", "country": "United States", "last_name": "Biller", "address2": null, "company": "My Company", "latitude": null, "longitude": null, "name": "Bob Biller", "country_code": "US", "province_code": "KY" }, "shipping_address": { "first_name": "Steve", "address1": "123 Shipping Street", "phone": "555-555-SHIP", "city": "Shippington", "zip": "K2P0S0", "province": "Kentucky", "country": "United States", "last_name": "Shipper", "address2": null, "company": "Shipping Company", "latitude": null, "longitude": null, "name": "Steve Shipper", "country_code": "US", "province_code": "KY" }, "customer": { "id": 1234567, "email": "john@test.com", "accepts_marketing": false, "created_at": null, "updated_at": null, "first_name": "John", "last_name": "Smith", "orders_count": 0, "state": "disabled", "total_spent": "0.00", "last_order_id": null, "note": null, "verified_email": true, "multipass_identifier": null, "tax_exempt": false, "phone": null, "tags": "", "last_order_name": null } }
Collection	collections/create, collections/delete, collections/update { "id": 327474488104976386, "handle": "mynewcollection", "title": "My New Collection", "updated_at": "2017-03-20T16:04:30-04:00", "body_html": "<b>Some HTML<\/b>", "published_at": "2017-03-20T13:04:30-04:00", "sort_order": "manual", "template_suffix": null, "published_scope": "global" }
CollectionPublication	collection_listings/add, collection_listings/remove, collection_listings/update { "collection_listing": { "collection_id": 327474488104976386, "updated_at": null, "body_html": "<b>Some HTML<\/b>", "default_product_image": null, "handle": "mynewcollection", "image": null, "title": "My New Collection", "sort_order": "manual", "published_at": "2017-03-20T16:04:30-04:00" } }
Customer	customers/create, customers/delete, customers/disable, customers/enable, customers/update { "id": 1234567, "email": "bob@biller.com", "accepts_marketing": true, "created_at": null, "updated_at": null, "first_name": "Bob", "last_name": "Biller", "orders_count": 0, "state": "disabled", "total_spent": "0.00", "last_order_id": null, "note": "This customer loves ice cream", "verified_email": true, "multipass_identifier": null, "tax_exempt": false, "phone": null, "tags": "", "last_order_name": null, "addresses": [ ] }
CustomerSavedSearch	customer_groups/create, customer_groups/delete, customer_groups/update { "id": 775454534, "name": "Repeat Customers", "created_at": "2017-03-20T16:04:30-04:00", "updated_at": "2017-03-20T16:04:30-04:00", "query": "orders_count:>1" }
DraftOrder	draft_orders/create, draft_orders/delete, draft_orders/update { "id": 123456, "note": null, "email": "jon@doe.ca", "taxes_included": false, "currency": "USD", "subtotal_price": "2537.00", "total_tax": "0.00", "total_price": "2702.22", "invoice_sent_at": null, "created_at": "2017-03-20T16:04:28-04:00", "updated_at": "2017-03-20T16:04:28-04:00", "tax_exempt": false, "completed_at": null, "name": "#D234", "status": "open", "line_items": [ { "variant_id": 808950810, "product_id": 632910392, "title": "IPod Nano - 8GB", "variant_title": "Pink", "sku": "IPOD2008PINK", "vendor": "Apple", "price": "199.00", "grams": 567, "quantity": 3, "requires_shipping": true, "taxable": true, "gift_card": false, "fulfillment_service": "manual", "tax_lines": [ ], "applied_discount": null, "name": "IPod Nano - 8GB - Pink", "properties": [ ], "custom": false }, { "variant_id": 808950810, "product_id": 632910392, "title": "IPod Nano - 8GB", "variant_title": "Pink", "sku": "IPOD2008PINK", "vendor": "Apple", "price": "199.00", "grams": 567, "quantity": 1, "requires_shipping": true, "taxable": true, "gift_card": false, "fulfillment_service": "manual", "tax_lines": [ ], "applied_discount": null, "name": "IPod Nano - 8GB - Pink", "properties": [ ], "custom": false }, { "variant_id": 457924702, "product_id": 632910392, "title": "IPod Nano - 8GB", "variant_title": "Black", "sku": "IPOD2008BLACK", "vendor": "Apple", "price": "199.00", "grams": 567, "quantity": 10, "requires_shipping": true, "taxable": true, "gift_card": false, "fulfillment_service": "manual", "tax_lines": [ ], "applied_discount": { "description": "bulk discount", "value": "10.0", "title": "Bulk Discount", "amount": "199.00", "value_type": "percentage" }, "name": "IPod Nano - 8GB - Black", "properties": [ ], "custom": false } ], "shipping_address": { "first_name": "Steve", "address1": "123 Shipping Street", "phone": "555-555-SHIP", "city": "Shippington", "zip": "40150", "province": "Kentucky", "country": "United States", "last_name": "Shipper", "address2": null, "company": "Shipping Company", "latitude": null, "longitude": null, "name": "Steve Shipper", "country_code": "US", "province_code": "KY" }, "billing_address": { "first_name": "Bob", "address1": "123 Billing Street", "phone": "555-555-BILL", "city": "Billtown", "zip": "K2P0B0", "province": "Kentucky", "country": "United States", "last_name": "Biller", "address2": null, "company": "My Company", "latitude": null, "longitude": null, "name": "Bob Biller", "country_code": "US", "province_code": "KY" }, "invoice_url": "https:\/\/checkout.local\/690933842\/invoices\/abcd1234abcd1234abcd1234abcd1234", "applied_discount": { "description": "loyalty", "value": "50.0", "title": "Loyalty", "amount": "50.00", "value_type": "fixed_amount" }, "order_id": null, "shipping_line": { "title": "Generic Shipping", "price": "10.00", "custom": true, "handle": null }, "tax_lines": [ { "price": "35.82", "rate": 0.06, "title": "State Tax" }, { "price": "11.94", "rate": 0.06, "title": "State Tax" }, { "price": "107.46", "rate": 0.06, "title": "State Tax" } ], "tags": "", "note_attributes": [ ], "customer": { "id": null, "email": "john@doe.ca", "accepts_marketing": false, "created_at": null, "updated_at": null, "first_name": "John", "last_name": "Smith", "orders_count": 0, "state": "disabled", "total_spent": "0.00", "last_order_id": null, "note": null, "verified_email": true, "multipass_identifier": null, "tax_exempt": false, "phone": null, "tags": "", "last_order_name": null, "default_address": { "id": null, "first_name": null, "last_name": null, "company": null, "address1": "123 Elm St.", "address2": null, "city": "Ottawa", "province": "Ontario", "country": "Canada", "zip": "K2H7A8", "phone": "123-123-1234", "name": "", "province_code": "ON", "country_code": "CA", "country_name": "Canada", "default": true } } }
Fulfillment	fulfillments/create, fulfillments/update { "id": 123456, "order_id": 123456, "status": "pending", "created_at": "2017-03-20T16:04:32-04:00", "service": null, "updated_at": "2017-03-20T16:04:32-04:00", "tracking_company": "UPS", "shipment_status": null, "email": "jon@doe.ca", "destination": { "first_name": "Steve", "address1": "123 Shipping Street", "phone": "555-555-SHIP", "city": "Shippington", "zip": "K2P0S0", "province": "Kentucky", "country": "United States", "last_name": "Shipper", "address2": null, "company": "Shipping Company", "latitude": null, "longitude": null, "name": "Steve Shipper", "country_code": "US", "province_code": "KY" }, "tracking_number": "1z827wk74630", "tracking_numbers": [ "1z827wk74630" ], "tracking_url": "http:\/\/wwwapps.ups.com\/etracking\/tracking.cgi?InquiryNumber1=1z827wk74630&TypeOfInquiryNumber=T&AcceptUPSLicenseAgreement=yes&submit=Track", "tracking_urls": [ "http:\/\/wwwapps.ups.com\/etracking\/tracking.cgi?InquiryNumber1=1z827wk74630&TypeOfInquiryNumber=T&AcceptUPSLicenseAgreement=yes&submit=Track" ], "receipt": { }, "line_items": [ { "id": 808950810, "variant_id": null, "title": "IPod Nano - 8GB", "quantity": 1, "price": "199.00", "grams": 567, "sku": "IPOD2008PINK", "variant_title": null, "vendor": null, "fulfillment_service": "manual", "product_id": 632910392, "requires_shipping": true, "taxable": true, "gift_card": false, "name": "IPod Nano - 8GB", "variant_inventory_management": null, "properties": [ ], "product_exists": true, "fulfillable_quantity": 1, "total_discount": "0.00", "fulfillment_status": null, "tax_lines": [ ] }, { "id": 199, "variant_id": null, "title": "IPod Nano - 8GB", "quantity": 1, "price": "199.00", "grams": 567, "sku": "IPOD2008PINK", "variant_title": null, "vendor": null, "fulfillment_service": "manual", "product_id": 632910392, "requires_shipping": true, "taxable": true, "gift_card": false, "name": "IPod Nano - 8GB", "variant_inventory_management": null, "properties": [ ], "product_exists": true, "fulfillable_quantity": 1, "total_discount": "5.00", "fulfillment_status": null, "tax_lines": [ ] } ] }
FulfillmentEvent	fulfillment_events/create, fulfillment_events/delete { "id": 1234567, "fulfillment_id": 123456, "status": "in_transit", "message": "Item is now in transit", "happened_at": "2017-03-20T16:04:31-04:00", "city": "Montreal", "province": "QC", "country": "CA", "zip": null, "address1": null, "latitude": null, "longitude": null, "shop_id": 690933842, "created_at": "2017-03-20T16:04:31-04:00", "updated_at": "2017-03-20T16:04:31-04:00", "estimated_delivery_at": null, "order_id": 123456 }
Order	orders/cancelled, orders/create, orders/delete, orders/fulfilled, orders/paid, orders/partially_fulfilled, orders/updated { "id": 123456, "email": "jon@doe.ca", "closed_at": null, "created_at": "2017-03-20T16:02:31-04:00", "updated_at": "2017-03-20T16:02:31-04:00", "number": 234, "note": null, "token": "123456abcd", "gateway": null, "test": true, "total_price": "403.00", "subtotal_price": "393.00", "total_weight": 0, "total_tax": "0.00", "taxes_included": false, "currency": "USD", "financial_status": "voided", "confirmed": false, "total_discounts": "5.00", "total_line_items_price": "398.00", "cart_token": null, "buyer_accepts_marketing": true, "name": "#9999", "referring_site": null, "landing_site": null, "cancelled_at": "2017-03-20T16:02:31-04:00", "cancel_reason": "customer", "total_price_usd": null, "checkout_token": null, "reference": null, "user_id": null, "location_id": null, "source_identifier": null, "source_url": null, "processed_at": null, "device_id": null, "browser_ip": null, "landing_site_ref": null, "order_number": 1234, "discount_codes": [ ], "note_attributes": [ ], "payment_gateway_names": [ "visa", "bogus" ], "processing_method": "", "checkout_id": null, "source_name": "web", "fulfillment_status": "pending", "tax_lines": [ ], "tags": "", "contact_email": "jon@doe.ca", "order_status_url": null, "line_items": [ { "id": 808950810, "variant_id": null, "title": "IPod Nano - 8GB", "quantity": 1, "price": "199.00", "grams": 567, "sku": "IPOD2008PINK", "variant_title": null, "vendor": null, "fulfillment_service": "manual", "product_id": 632910392, "requires_shipping": true, "taxable": true, "gift_card": false, "name": "IPod Nano - 8GB", "variant_inventory_management": null, "properties": [ ], "product_exists": true, "fulfillable_quantity": 1, "total_discount": "0.00", "fulfillment_status": null, "tax_lines": [ ] }, { "id": 199, "variant_id": null, "title": "IPod Nano - 8GB", "quantity": 1, "price": "199.00", "grams": 567, "sku": "IPOD2008PINK", "variant_title": null, "vendor": null, "fulfillment_service": "manual", "product_id": 632910392, "requires_shipping": true, "taxable": true, "gift_card": false, "name": "IPod Nano - 8GB", "variant_inventory_management": null, "properties": [ ], "product_exists": true, "fulfillable_quantity": 1, "total_discount": "5.00", "fulfillment_status": null, "tax_lines": [ ] } ], "shipping_lines": [ { "id": 1234567, "title": "Generic Shipping", "price": "10.00", "code": null, "source": "spiffy", "phone": null, "requested_fulfillment_service_id": null, "delivery_category": null, "carrier_identifier": null, "tax_lines": [ ] } ], "billing_address": { "first_name": "Bob", "address1": "123 Billing Street", "phone": "555-555-BILL", "city": "Billtown", "zip": "K2P0B0", "province": "Kentucky", "country": "United States", "last_name": "Biller", "address2": null, "company": "My Company", "latitude": null, "longitude": null, "name": "Bob Biller", "country_code": "US", "province_code": "KY" }, "shipping_address": { "first_name": "Steve", "address1": "123 Shipping Street", "phone": "555-555-SHIP", "city": "Shippington", "zip": "K2P0S0", "province": "Kentucky", "country": "United States", "last_name": "Shipper", "address2": null, "company": "Shipping Company", "latitude": null, "longitude": null, "name": "Steve Shipper", "country_code": "US", "province_code": "KY" }, "fulfillments": [ ], "refunds": [ ], "customer": { "id": 1234567, "email": "john@test.com", "accepts_marketing": false, "created_at": null, "updated_at": null, "first_name": "John", "last_name": "Smith", "orders_count": 0, "state": "disabled", "total_spent": "0.00", "last_order_id": null, "note": null, "verified_email": true, "multipass_identifier": null, "tax_exempt": false, "phone": null, "tags": "", "last_order_name": null, "default_address": { "id": 1234567, "first_name": null, "last_name": null, "company": null, "address1": "123 Elm St.", "address2": null, "city": "Ottawa", "province": "Ontario", "country": "Canada", "zip": "K2H7A8", "phone": "123-123-1234", "name": "", "province_code": "ON", "country_code": "CA", "country_name": "Canada", "default": false } } }
OrderTransaction	order_transactions/create { "id": 23456, "order_id": 123456, "amount": "11.50", "kind": "authorization", "gateway": "visa", "status": "success", "message": null, "created_at": "2017-03-20T16:02:33-04:00", "test": false, "authorization": "1001", "currency": null, "location_id": null, "user_id": null, "parent_id": null, "device_id": null, "receipt": { }, "error_code": null, "source_name": "web", "payment_details": { "credit_card_bin": null, "avs_result_code": null, "cvv_result_code": null, "credit_card_number": "•••• •••• •••• 1234", "credit_card_company": "Visa" } }
Product	products/create, products/delete, products/update { "id": 327475578523353102, "title": "Example T-Shirt", "body_html": null, "vendor": "Acme", "product_type": "Shirts", "created_at": null, "handle": "example-t-shirt", "updated_at": null, "published_at": "2017-03-20T16:04:28-04:00", "template_suffix": null, "published_scope": "global", "tags": "mens t-shirt example", "variants": [ { "id": 1234567, "product_id": 327475578523353102, "title": "", "price": "19.99", "sku": "example-shirt-s", "position": 0, "grams": 200, "inventory_policy": "deny", "compare_at_price": "24.99", "fulfillment_service": "manual", "inventory_management": null, "option1": "Small", "option2": null, "option3": null, "created_at": null, "updated_at": null, "taxable": true, "barcode": null, "image_id": null, "inventory_quantity": 75, "weight": 0.44, "weight_unit": "lb", "old_inventory_quantity": 75, "requires_shipping": true }, { "id": 1234568, "product_id": 327475578523353102, "title": "", "price": "19.99", "sku": "example-shirt-m", "position": 0, "grams": 200, "inventory_policy": "deny", "compare_at_price": "24.99", "fulfillment_service": "manual", "inventory_management": "spiffy", "option1": "Medium", "option2": null, "option3": null, "created_at": null, "updated_at": null, "taxable": true, "barcode": null, "image_id": null, "inventory_quantity": 50, "weight": 0.44, "weight_unit": "lb", "old_inventory_quantity": 50, "requires_shipping": true } ], "options": [ { "id": 12345, "product_id": 327475578523353102, "name": "Title", "position": 1, "values": [ "Small", "Medium" ] } ], "images": [ { "id": 1234567, "product_id": 327475578523353102, "position": 0, "created_at": null, "updated_at": null, "src": "\/\/cdn.spiffy.com\/s\/assets\/spiffy_shirt-39bb555874ecaeed0a1170417d58bbcf792f7ceb56acfe758384f788710ba635.png", "variant_ids": [ ] } ], "image": null }
ProductPublication	product_listings/add, product_listings/remove, product_listings/update { "product_listing": { "product_id": 327475578523353102, "created_at": null, "updated_at": null, "body_html": null, "handle": "example-t-shirt", "product_type": "Shirts", "title": "Example T-Shirt", "vendor": "Acme", "available": true, "tags": "mens t-shirt example", "published_at": "2017-03-20T16:02:34-04:00", "images": [ { "id": 1234567, "created_at": null, "position": 0, "updated_at": null, "product_id": 327475578523353102, "src": "\/\/cdn.spiffy.com\/s\/assets\/spiffy_shirt-39bb555874ecaeed0a1170417d58bbcf792f7ceb56acfe758384f788710ba635.png", "variant_ids": [ ] } ], "options": [ { "id": 12345, "name": "Title", "product_id": 327475578523353102, "position": 1 } ], "variants": [ { "id": 1234567, "title": "", "option_values": [ { "option_id": 12345, "name": "Title", "value": "Small" } ], "price": "19.99", "formatted_price": "$19.99", "compare_at_price": "24.99", "grams": 200, "requires_shipping": true, "sku": "example-shirt-s", "barcode": null, "taxable": true, "position": 0, "available": true, "inventory_policy": "deny", "inventory_quantity": 75, "inventory_management": null, "fulfillment_service": "manual", "weight": 0.44, "weight_unit": "lb", "image_id": null, "created_at": null, "updated_at": null }, { "id": 1234568, "title": "", "option_values": [ { "option_id": 12345, "name": "Title", "value": "Medium" } ], "price": "19.99", "formatted_price": "$19.99", "compare_at_price": "24.99", "grams": 200, "requires_shipping": true, "sku": "example-shirt-m", "barcode": null, "taxable": true, "position": 0, "available": true, "inventory_policy": "deny", "inventory_quantity": 50, "inventory_management": "spiffy", "fulfillment_service": "manual", "weight": 0.44, "weight_unit": "lb", "image_id": null, "created_at": null, "updated_at": null } ] } }
Refund	refunds/create { "id": 1234567, "order_id": 123456, "created_at": "2017-03-20T16:02:33-04:00", "note": "Things were damaged", "restock": true, "user_id": 799407056, "processed_at": "2017-03-20T16:02:33-04:00", "refund_line_items": [ { "id": 808950883, "quantity": 1, "line_item_id": 808950810, "subtotal": 199.0, "total_tax": 0.0, "line_item": { "id": 808950810, "variant_id": null, "title": "IPod Nano - 8GB", "quantity": 1, "price": "199.00", "grams": 567, "sku": "IPOD2008PINK", "variant_title": null, "vendor": null, "fulfillment_service": "manual", "product_id": 632910392, "requires_shipping": true, "taxable": true, "gift_card": false, "name": "IPod Nano - 8GB", "variant_inventory_management": null, "properties": [ ], "product_exists": true, "fulfillable_quantity": 1, "total_discount": "0.00", "fulfillment_status": null, "tax_lines": [ ] } }, { "id": 272, "quantity": 1, "line_item_id": 199, "subtotal": 194.0, "total_tax": 0.0, "line_item": { "id": 199, "variant_id": null, "title": "IPod Nano - 8GB", "quantity": 1, "price": "199.00", "grams": 567, "sku": "IPOD2008PINK", "variant_title": null, "vendor": null, "fulfillment_service": "manual", "product_id": 632910392, "requires_shipping": true, "taxable": true, "gift_card": false, "name": "IPod Nano - 8GB", "variant_inventory_management": null, "properties": [ ], "product_exists": true, "fulfillable_quantity": 1, "total_discount": "5.00", "fulfillment_status": null, "tax_lines": [ ] } } ], "transactions": [ { "id": 42424242, "order_id": 123456, "amount": "75.00", "kind": "refund", "gateway": "bogus", "status": "success", "message": "This is a refund", "created_at": null, "test": false, "authorization": null, "currency": null, "location_id": null, "user_id": null, "parent_id": null, "device_id": null, "receipt": { }, "error_code": null, "source_name": "web" }, { "id": 42424243, "order_id": 123456, "amount": "10.00", "kind": "refund", "gateway": "bogus", "status": "success", "message": null, "created_at": null, "test": false, "authorization": null, "currency": null, "location_id": null, "user_id": null, "parent_id": null, "device_id": null, "receipt": { }, "error_code": null, "source_name": "web" } ], "order_adjustments": [ ] }
Shop	app/uninstalled, shop/update { "id": 1234567, "name": "Super Toys", "email": "super@supertoys.com", "domain": null, "created_at": null, "province": "Tennessee", "country": "US", "address1": "190 MacLaren Street", "zip": "37178", "city": "Houston", "source": null, "phone": "3213213210", "updated_at": null, "customer_email": null, "latitude": null, "longitude": null, "primary_location_id": null, "primary_locale": "en", "address2": null, "country_code": "US", "country_name": "United States", "currency": "USD", "timezone": "(GMT-05:00) Eastern Time (US & Canada)", "iana_timezone": null, "shop_owner": "N\/A", "money_format": "$", "money_with_currency_format": "$ USD", "weight_unit": "kg", "province_code": "TN", "taxes_included": null, "tax_shipping": null, "county_taxes": null, "plan_display_name": null, "plan_name": null, "has_discounts": null, "has_gift_cards": false, "spiffy_domain": null, "google_apps_domain": null, "google_apps_login_enabled": null, "money_in_emails_format": "$", "money_with_currency_in_emails_format": "$ USD", "eligible_for_payments": true, "requires_extra_payments_agreement": false, "password_enabled": null, "has_storefront": false, "eligible_for_card_reader_giveaway": false, "finances": true, "setup_required": false, "force_ssl": false }
Theme	themes/create, themes/delete, themes/publish, themes/update { "id": null, "name": "Comfort", "created_at": "2017-03-20T16:02:33-04:00", "updated_at": "2017-03-20T16:02:33-04:00", "role": "main", "theme_store_id": 1234, "previewable": true, "processing": false }

What you can do with a Webhook

The Spiffy Stores API lets you do the following with the Webhook resource. More detailed versions of these general actions may be available:

• GET /admin/webhooks.json
  Receive a list of all Webhooks
  
  
• GET /admin/webhooks/count.json?topic=orders/create
  Receive a count of all Webhooks
  
  
• GET /admin/webhooks/#{id}.json
  Receive a single Webhook
  
  
• POST /admin/webhooks.json
  Create a new Webhook
  
  
• PUT /admin/webhooks/#{id}.json
  Modify an existing Webhook
  
  
• DELETE /admin/webhooks/#{id}.json
  Remove a Webhook from the database
  
  

Webhook properties

id	{ "id": 901431826 } The unique numeric identifier for the webhook.
address	{ "address": "https://apple.com/uninstall" } The URI where the webhook should send the POST request when the event occurs.
format	{ "format": "json" } The format in which the webhook should send the data. Valid values are json and xml.
topic	{ "topic": "app/uninstalled" } The event that will trigger the webhook. Valid values are: app/uninstalled carts/create carts/update checkouts/create checkouts/delete checkouts/update collection_listings/add collection_listings/remove collection_listings/update collections/create collections/delete collections/update customer_groups/create customer_groups/delete customer_groups/update customers/create customers/delete customers/disable customers/enable customers/update draft_orders/create draft_orders/delete draft_orders/update fulfillment_events/create fulfillment_events/delete fulfillments/create fulfillments/update order_transactions/create orders/cancelled orders/create orders/delete orders/fulfilled orders/paid orders/partially_fulfilled orders/updated product_listings/add product_listings/remove product_listings/update products/create products/delete products/update refunds/create shop/update themes/create themes/delete themes/publish themes/update
source	{ "source": "api" } The source which created the webhook. Valid values are api and manual.
created_at	{ "created_at": "2012-09-28T11:50:07-04:00" } The date and time when the webhook was created. The API returns this value in ISO 8601 format.
updated_at	{ "updated_at": "2012-09-28T11:50:07-04:00" } The date and time when the webhook was updated. The API returns this value in ISO 8601 format.

Endpoints

GET /api/webhooks.json

Get a list of webhooks.

Optional Parameters

limit	Number of results returned. The default is 30, with a maximum of 50 in a single request.
page	The number of the page to return. The number of results per page is set by the limit parameter. If more results are required, then submit the request again, increasing the page number each time.
since_id	Limit the results to only include objects which have an id greater than the given value.
address	Limit the results to only include webhooks with the given address (URI).
topic	Limit the results to only include webhooks with the given topic.
source	Limit the results to only include webhooks with the given source.
created_at_min	Return only the webhooks created after the given date and time. Use the format "2014-12-31 12:00".
created_at_max	Return only the webhooks created before the given date and time. Use the format "2014-12-31 12:00".
updated_at_min	Return only the webhooks updated after the given date and time. Use the format "2014-12-31 12:00".
updated_at_max	Return only the webhooks updated before the given date and time. Use the format "2014-12-31 12:00".
fields	A comma-separated list of fields to return in the response.

Example Request and Response

GET /api/webhooks.json

HTTP/1.1 200 OK
{
  "webhooks": [
    {
      "id": 4759306,
      "address": "https:\/\/apple.com",
      "topic": "orders\/create",
      "created_at": "2017-03-20T16:02:17-04:00",
      "updated_at": "2017-03-20T16:02:17-04:00",
      "format": "json"
    },
    ...
  ]
}

Examples using filters

GET /api/webhooks.json?fields=id,address

GET /api/webhooks.json?since_id=4759306

GET /api/webhooks/count.json

Return a count of the number of webhooks.

Optional Parameters

since_id	Limit the results to only include objects which have an id greater than the given value.
address	Limit the results to only include webhooks with the given address (URI).
topic	Limit the results to only include webhooks with the given topic.
source	Limit the results to only include webhooks with the given source.
created_at_min	Return only the webhooks created after the given date and time. Use the format "2014-12-31 12:00".
created_at_max	Return only the webhooks created before the given date and time. Use the format "2014-12-31 12:00".
updated_at_min	Return only the webhooks updated after the given date and time. Use the format "2014-12-31 12:00".
updated_at_max	Return only the webhooks updated before the given date and time. Use the format "2014-12-31 12:00".

Example Request and Response

GET /api/webhooks/count.json

HTTP/1.1 200 OK

{
  "count": 15
}

Examples using filters

GET /api/webhooks/count.json?topic=orders/create

Count all of the webhooks for your shop.

GET /admin/webhooks/count.json

HTTP/1.1 200 OK
{
  "count": 25
}

GET /admin/webhooks/4759306.json

Get a single webhook

fields

A comma-separated list of the properties you want returned for each item in the result list. Use this parameter to restrict the returned list of items to showing only those properties you specify.

Get a single webhook by its id.

GET /admin/webhooks/#{id}.json

HTTP/1.1 200 OK
{
  "webhook": {
    "id": 4759306,
    "address": "http:\/\/apple.com",
    "topic": "orders\/create",
    "created_at": "2017-03-20T16:02:17-04:00",
    "updated_at": "2017-03-20T16:02:17-04:00",
    "format": "json",
    "fields": [
    ],
    "metafield_namespaces": [
    ]
  }
}

POST /api/webhooks.json

Every webhook needs a topic and an address. Failure to have a topic or an address will result in a 422 - Unprocessable Entity error.

format	Use this parameter to select the format to receive the data in. Valid values are json and xml. (default: json)

After installing a Spiffy Stores App, it’s a pain for store owners to have to manually install webhooks the app needs. Automate that by using this API call.

POST /admin/webhooks.json

{
  "webhook": {
    "topic": "orders\/create",
    "address": "http:\/\/whatever.hostname.com\/",
    "format": "json"
  }
}

Response

HTTP/1.1 201 Created
{
  "webhook": {
    "id": 1047897619,
    "address": "http:\/\/whatever.hostname.com\/",
    "topic": "orders\/create",
    "created_at": "2017-03-20T16:02:33-04:00",
    "updated_at": "2017-03-20T16:02:33-04:00",
    "format": "json",
    "fields": [
    ],
    "metafield_namespaces": [
    ]
  }
}

Trying to create a webhook without an address or topic will return an error

POST /admin/webhooks.json

{
  "webhook": {
    "body": "foobar"
  }
}

Response

HTTP/1.1 422 Unprocessable Entity
{
  "errors": {
    "topic": [
      "can't be blank",
      "Invalid topic specified. Topics allowed: app\/uninstalled, carts\/create, carts\/update, catalogs\/create, catalogs\/delete, channels\/delete, checkouts\/create, checkouts\/delete, checkouts\/update, collection_listings\/add, collection_listings\/remove, collection_listings\/update, collection_publications\/create, collection_publications\/delete, collection_publications\/update, collections\/create, collections\/delete, collections\/update, customer_groups\/create, customer_groups\/delete, customer_groups\/update, customers\/create, customers\/delete, customers\/disable, customers\/enable, customers\/update, disputes\/create, disputes\/update, draft_orders\/create, draft_orders\/delete, draft_orders\/update, fulfillment_events\/create, fulfillment_events\/delete, fulfillments\/create, fulfillments\/update, order_transactions\/create, orders\/cancelled, orders\/create, orders\/delete, orders\/fulfilled, orders\/paid, orders\/partially_fulfilled, orders\/updated, product_listings\/add, product_listings\/remove, product_listings\/update, product_publications\/create, product_publications\/delete, product_publications\/update, products\/create, products\/delete, products\/update, refunds\/create, shop\/update, tax_services\/create, tax_services\/update, themes\/create, themes\/delete, themes\/publish, themes\/update, variants\/in_stock, variants\/out_of_stock"
    ],
    "address": [
      "can't be blank"
    ]
  }
}

PUT /admin/webhooks/4759306.json

Update a webhook's topic and/or address URIs.

Change a webhook so that it POSTs to a different address:

PUT /admin/webhooks/#{id}.json

{
  "webhook": {
    "id": 4759306,
    "address": "http:\/\/somewhere-else.com\/"
  }
}

Response

HTTP/1.1 200 OK
{
  "webhook": {
    "id": 4759306,
    "address": "http:\/\/somewhere-else.com\/",
    "topic": "orders\/create",
    "created_at": "2017-03-20T16:02:17-04:00",
    "updated_at": "2017-03-20T16:04:29-04:00",
    "format": "json",
    "fields": [
    ],
    "metafield_namespaces": [
    ]
  }
}

DELETE /api/webhooks/WEBHOOK_ID.json

Delete a webhook

Remove an existing webhook from a store

DELETE /admin/webhooks/#{id}.json

Response

HTTP/1.1 200 OK
{}

Further Reference

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