Backend Integrations & the Spree Commerce Hub

SpreeConf 2014, New York City

Transcript

1. Backend Integrations & the Spree Commerce Hub SpreeConf 2014, NYC
2. Brian Quinn CTO & Co founder of Spree Commerce, Inc. Twitter: @briandq Github: BDQ
3. What is the hub?
4. A platform
5. A platform to simplify the backend logistics for commerce businesses.
6. A platform to decouple the backend processes from the storefront.
7. A suite of integrations
8. A suite of integrations to get your commerce business moving faster.
9. A suite of tools
10. A suite of tools to help you monitor and manage your integrations.
11. A suite of tools to help you implement custom integrations.
12. A peace of mind
13. A peace of mind that everything is happening as it should.
14. A peace of mind that everything is happening as it should. OR WE’LL COME FIND YOU!
15. A peace of mind that everything is happening as it should. OR WE’LL COME FIND YOU!
16. A peace of mind that everything is happening as it should. OR WE’LL COME HELP YOU!
17. What problems does it solve? The Acme Widgets Store
18. What problems does it solve? The Acme Widgets Store ➡ Third Party Logistics
19. What problems does it solve? The Acme Widgets Store ➡ Third Party Logistics ➡ Accounting Application
20. What problems does it solve? The Acme Widgets Store ➡ Third Party Logistics ➡ Accounting Application ➡ Multi-channel Sales
21. What problems does it solve? The Acme Widgets Store ➡ Third Party Logistics ➡ Accounting Application ➡ Multi-channel Sales ➡ Customer Service
22. What problems does it solve? The Acme Widgets Store ➡ Third Party Logistics ➡ Accounting Application ➡ Multi-channel Sales ➡ Customer Service ➡ Analytics & Marketing
23. What problems does it solve? The Acme Widgets Store ➡ Third Party Logistics ➡ Accounting Application ➡ Multi-channel Sales ➡ Customer Service ➡ Analytics & Marketing
24. What problems does it solve? The Acme Widgets Store ➡ Third Party Logistics ➡ Accounting Application ➡ Multi-channel Sales ➡ Customer Service ➡ Analytics & Marketing And much more!
25. History - Timeline
26. History - Timeline ➡ Version 1 went into production late 2012
27. History - Timeline ➡ Version 1 went into production late 2012 ➡ Version 2..4 deployed up to Q1 2013
28. History - Timeline ➡ Version 1 went into production late 2012 ➡ Version 2..4 deployed up to Q1 2013 ➡ Version 5 - SpreeConf DC - May 2013
29. History - Timeline ➡ Version 1 went into production late 2012 ➡ Version 2..4 deployed up to Q1 2013 ➡ Version 5 - SpreeConf DC - May 2013 ➡ called the ‘Integrator’
30. History - Timeline ➡ Version 1 went into production late 2012 ➡ Version 2..4 deployed up to Q1 2013 ➡ Version 5 - SpreeConf DC - May 2013 ➡ called the ‘Integrator’ ➡ Version 6 - SpreeConf NYC - February 2014
31. History - Timeline ➡ Version 1 went into production late 2012 ➡ Version 2..4 deployed up to Q1 2013 ➡ Version 5 - SpreeConf DC - May 2013 ➡ called the ‘Integrator’ ➡ Version 6 - SpreeConf NYC - February 2014 ➡ called the ‘Spree Commerce Hub’
32. History - Integrations ➡ NetSuite ➡ OpenERP ➡ QuickBooks ➡ Quiet Logistics ➡ Shipwire ➡ DotCom ➡ PCH International ➡ Fosdick ➡ VPD ➡ RLM ➡ Simparel ➡ Twilio ➡ Zendesk ➡ Desk ➡ Tender ➡ Mandrill ➡ Exact Target ➡ SMTP
33. We’re off to a great start
34. We’re off to a great start and there’s lots more to come.
35. Challenge 1: How do we make things easier for everyone?
36. Challenge 2: How do we make it accessible to everyone?
38. Simplified API The API for commerce
39. Three core terms
40. Three core terms Object ➡ A JSON representation of an order, product, customer, shipment, return, etc.
41. Three core terms Object ➡ A JSON representation of an order, product, customer, shipment, return, etc. Event ➡ An interesting change to an object.
42. Three core terms Object ➡ A JSON representation of an order, product, customer, shipment, return, etc. Event ➡ An interesting change to an object. Webhook ➡ HTTP POST to predefined URL.
43. Common Use Cases ➡ Third Party Logistics ➡ Accounting & ERP ➡ Multi channel sales ➡ Communications ➡ Customer Service
44. Third Party Logistics Use Case: “I want to tell my 3PL when there’s a new shipment to fulfill.” ➡ Object: Shipment ➡ Event: shipment:ready ➡ Webhook: /add_shipment
45. Third Party Logistics Use Case: “I want to tell my 3PL when there’s a new shipment to fulfill.” ➡ Object: Shipment ➡ Event: shipment:ready ➡ Webhook: /add_shipment
46. Third Party Logistics Use Case: “I want to tell my 3PL when there’s a new shipment to fulfill.” ➡ Object: Shipment ➡ Event: shipment:ready ➡ Webhook: /add_shipment
47. Third Party Logistics Use Case: “I want to update my store when a shipment has dispatched.” ➡ Object: Shipment ➡ Event: schedule ➡ Webhook: /get_shipments
48. Third Party Logistics Use Case: “I want to update my store with my 3PL’s stock levels.” ➡ Object: Inventory ➡ Event: schedule ➡ Webhook: /get_inventory
49. Accounting & ERP Use Case: “I want keep my accounts up to date with all orders my store front.” ➡ Object: Order ➡ Event: order:created ➡ Webhook: /add_order
50. Accounting & ERP Use Case: “I want keep my accounts up to date with all orders my store front.” ➡ Object: Order ➡ Event: order:created ➡ Webhook: /add_order
51. Accounting & ERP Use Case: “I want keep my accounts up to date with all orders my store front.” ➡ Object: Order ➡ Event: order:created ➡ Webhook: /add_order
52. Accounting & ERP ➡ Object: Order ➡ Event: order:updated ➡ Webhook: /update_order Use Case: “I want keep my accounts up to date with all orders my store front.”
53. Accounting & ERP Use Case: “I need to import Products from my ERP to my store front.” ➡ Object: Product ➡ Event: schedule ➡ Webhook: /get_products
54. Multi Channel Sales Use Case: “I’d like to consolidate & process all my orders on a single platform.” ➡ Object: Order ➡ Event: schedule ➡ Webhook: /get_orders
55. Multi Channel Sales Use Case: “I’d like to consolidate & process all my orders on a single platform.” ➡ Object: Order ➡ Event: schedule ➡ Webhook: /get_orders
56. Use Case: “I want to keep stock levels in-sync across all my sales channels.” ➡ Object: Inventory ➡ Event: inventory:updated ➡ Webhook: /set_inventory Multi Channel Sales
57. Communications Use Case: “I want to send a user an email after they complete an order” ➡ Object: Order ➡ Event: order:created ➡ Webhook: /send_email
58. Communications Use Case: “I want to send a user an email after they complete an order” ➡ Object: Order ➡ Event: order:created ➡ Webhook: /send_email
59. Communications Use Case: “I want to send a user an email after they complete an order” ➡ Object: Order ➡ Event: order:created ➡ Webhook: /send_email
60. Communications Use Case: “I want to send a user an email after they cancel an order” ➡ Object: Order ➡ Event: order:cancelled ➡ Webhook: /send_email
61. Communications Use Case: “I want to send a user an email after their order ships” ➡ Object: Shipment ➡ Event: shipment:confirm ➡ Webhook: /send_email
62. Communications Use Case: “I want to send a user a SMS after their order ships” ➡ Object: Shipment ➡ Event: shipment:confirm ➡ Webhook: /send_sms
63. Customer Service Use Case: “I need to create a support ticket for high-risk orders” ➡ Object: Order ➡ Event: order:created ➡ Webhook: /create_ticket
64. Customer Service Use Case: “I need to create a support ticket for high-risk orders” ➡ Object: Order ➡ Event: order:created ➡ Webhook: /create_ticket
65. Customer Service Use Case: “I need to create a support ticket for high-risk orders” ➡ Object: Order ➡ Event: order:created ➡ Webhook: /create_ticket
66. Use Cases Summary
67. Use Cases Summary ➡ 5 business areas
68. Use Cases Summary ➡ 5 business areas ➡ 13 use cases
69. Use Cases Summary ➡ 5 business areas ➡ 13 use cases ➡ 15 vendors
70. Use Cases Summary ➡ 5 business areas ➡ 13 use cases ➡ 15 vendors All solved with 3 basic ideas:
71. Use Cases Summary ➡ 5 business areas ➡ 13 use cases ➡ 15 vendors All solved with 3 basic ideas: ➡ Objects
72. Use Cases Summary ➡ 5 business areas ➡ 13 use cases ➡ 15 vendors All solved with 3 basic ideas: ➡ Objects ➡ Events
73. Use Cases Summary ➡ 5 business areas ➡ 13 use cases ➡ 15 vendors All solved with 3 basic ideas: ➡ Objects ➡ Events ➡ Webhooks
74. The Hub Up close and personal
75. Objects It’s all about objects!
76. It’s all about Objects
77. Object Basics Object ➡ JSON ➡ predefined schemas
78. Object Basics ➡ Required Attributes ➡ id - unique identifier Object ➡ JSON ➡ predefined schemas
79. Object Basics ➡ Required Attributes ➡ id - unique identifier ➡ Suggested Attributes ➡ status - objects’ state Object ➡ JSON ➡ predefined schemas
80. Objects Orders Products Carts Customers
81. Objects Orders Products Carts Customers Inventory Payments Shipments Returns
82. Order Object ➡ email ➡ currency ➡ totals ➡ line_items ➡ billing_address Order ➡ channel ➡ placed_on ➡ payments ➡ shipments ➡ shipping_address
83. Order JSON { "order": { "id": "R154085346", "status": "complete", "channel": "spree", "email": "spree@example.com", "currency": "USD", "placed_on": "2014-02-03T17:29:15.219Z", "line_items": [ { "name": "Spree T-Shirt", "sku": "SPREE-T-SHIRT", "external_ref": "", Order
84. Objects have schemas ➡ Building `The API for commerce`
85. Objects have schemas ➡ Building `The API for commerce` ➡ Public schema for JSON representation of core commerce objects:
86. Objects have schemas ➡ Building `The API for commerce` ➡ Public schema for JSON representation of core commerce objects: ➡ orders, products, customers, returns, etc
87. Objects have schemas ➡ Building `The API for commerce` ➡ Public schema for JSON representation of core commerce objects: ➡ orders, products, customers, returns, etc
88. Objects have schemas ➡ Building `The API for commerce` ➡ Public schema for JSON representation of core commerce objects: ➡ orders, products, customers, returns, etc ➡ Hub Official Format
90. Order JSON-Schema Order { "type": "object", "required": ["id", "status", "channel"], "properties": { "id": { "type": "string" }, "channel": { "type": "string" }, "currency": { "type": "string" }, "placed_on": { "type": "string" }, "status": { "type": "string" }, "totals": { "type": "object", "required": ["item","adjustment", "tax", "shipping", "... "properties": {
91. https://hubapp.io
96. Need icon + more fake notifications
97. Need icon + more fake notifications
98. Need icon + more fake notifications
101. Extending Objects Adding what you need.
102. Custom Order - Simple { "order": { "id": "R154085346", "status": "complete", "channel": "spree", "email": "spree@example.com", "currency": "USD", "placed_on": "2014-02-03T17:29:15.219Z", "risk_level": "low", "line_items": [ { "name": "Spree T-Shirt", "sku": "SPREE-T-SHIRT", Order
103. Custom Order - Simple { "order": { "id": "R154085346", "status": "complete", "channel": "spree", "email": "spree@example.com", "currency": "USD", "placed_on": "2014-02-03T17:29:15.219Z", "risk_level": "low", "line_items": [ { "name": "Spree T-Shirt", "sku": "SPREE-T-SHIRT", Order
104. Custom Order - Object { "order": { "id": "R154085346", "status": "complete", "channel": "spree", "email": "spree@example.com", "currency": "USD", "placed_on": "2014-02-03T17:29:15.219Z", "risk": { "level": " low", "score": 9 }, "line_items": [ Order
105. Custom Order - Object { "order": { "id": "R154085346", "status": "complete", "channel": "spree", "email": "spree@example.com", "currency": "USD", "placed_on": "2014-02-03T17:29:15.219Z", "risk": { "level": " low", "score": 9 }, "line_items": [ Order
106. Custom Object { "pirate": { "id": "ARRGH1", "status": "angry", "name": "Captain Blue Beard", "port": "Basse-Terre", "ships": [ { "name": "Blue Bell", "type": "frigate" } ], "parrots": [ { Pirate
107. Push API Getting objects in
108. Pushing Objects ➡ Simple Push API
109. Pushing Objects ➡ Simple Push API ➡ https://push.hubapp.io
110. Pushing Objects ➡ Simple Push API ➡ https://push.hubapp.io ➡ Secure - unique token per push
111. Pushing Objects ➡ Simple Push API ➡ https://push.hubapp.io ➡ Secure - unique token per push ➡ Fast - validated asynchronously
112. Pushing Objects ➡ Simple Push API ➡ https://push.hubapp.io ➡ Secure - unique token per push ➡ Fast - validated asynchronously ➡ Customizable - attributes & objects
113. Pushing Objects ➡ Simple Push API ➡ https://push.hubapp.io ➡ Secure - unique token per push ➡ Fast - validated asynchronously ➡ Customizable - attributes & objects ➡ Partial updates
114. Pushing Objects ➡ Simple Push API ➡ https://push.hubapp.io ➡ Secure - unique token per push ➡ Fast - validated asynchronously ➡ Customizable - attributes & objects ➡ Partial updates
115. Pushing Objects ➡ Simple Push API ➡ https://push.hubapp.io ➡ Secure - unique token per push ➡ Fast - validated asynchronously ➡ Customizable - attributes & objects ➡ Partial updates
116. Pushing Objects ➡ Simple Push API ➡ https://push.hubapp.io ➡ Secure - unique token per push ➡ Fast - validated asynchronously ➡ Customizable - attributes & objects ➡ Partial updates
117. Pushing Objects ➡ Simple Push API ➡ https://push.hubapp.io ➡ Secure - unique token per push ➡ Fast - validated asynchronously ➡ Customizable - attributes & objects ➡ Partial updates
118. Push Example - Single { "orders": [ { "id": "R154085346", "status": "complete", "channel": "spree", "email": "spree@example.com", "currency": "USD", ... } ] } POST
119. Push Example - Single { "orders": [ { "id": "R154085346", "status": "complete", "channel": "spree", "email": "spree@example.com", "currency": "USD", ... } ] } POST { "orders": 1 } Response: 202
120. Push Example - Multiple { "orders": [ { "id": "R154085346", "status": "complete", "channel": "spree", "email": "spree@example.com", "currency": "USD" } , { "id": "R154085347", "status": "complete", "channel": "spree", POST
121. Push Example - Multiple { "orders": [ { "id": "R154085346", "status": "complete", "channel": "spree", "email": "spree@example.com", "currency": "USD" } , { "id": "R154085347", "status": "complete", "channel": "spree", POST { "orders": 2 } Response: 202
122. Push Example - Objects { "orders": [ { "id": "R154085346", "status": "complete", "channel": "spree", "email": "spree@example.com", "currency": "USD" } ] "products": [ { "id": "ROR-123", "name": "Ruby on Rails Tote", POST
123. Push Example - Objects { "orders": [ { "id": "R154085346", "status": "complete", "channel": "spree", "email": "spree@example.com", "currency": "USD" } ] "products": [ { "id": "ROR-123", "name": "Ruby on Rails Tote", POST { "orders": 1, "products": 1 } Response: 202
124. Push Example - Custom Object { "pirates": [ { "id": "ARRGH1", "status": "angry", "name": "Captain Blue Beard", "email": "cbb@example.com", "ships": [ { "name": "Blue Bell", "type": "frigate" } ] POST
125. Push Example - Custom Object { "pirates": [ { "id": "ARRGH1", "status": "angry", "name": "Captain Blue Beard", "email": "cbb@example.com", "ships": [ { "name": "Blue Bell", "type": "frigate" } ] POST { "pirates": 1 } Response: 202
126. Push Example - Partial { "orders": [ { "id": "R154085346", "status": "complete", "channel": "spree", "currency": "USD", ... } ] } Push 1
127. Push Example - Partial { "orders": [ { "id": "R154085346", "status": "complete", "channel": "spree", "currency": "USD", ... } ] } Push 1 { "orders": [ { "id": "R154085346", "status": "cancelled" } ] } Push 2
128. Push Example - Partial { "orders": [ { "id": "R154085346", "status": "complete", "channel": "spree", "currency": "USD", ... } ] } Push 1 { "orders": [ { "id": "R154085346", "status": "cancelled" } ] } Push 2 { "order": { "id": "R154085346", "status": "cancelled", "channel": "spree", "currency": "USD" ... } } Result
129. Authentication ➡ HMAC
130. Authentication ➡ HMAC ➡ json + secret key + timestamp (UTC)
131. Authentication ➡ HMAC ➡ json + secret key + timestamp (UTC) ➡ Each push is only valid for:
132. Authentication ➡ HMAC ➡ json + secret key + timestamp (UTC) ➡ Each push is only valid for: ➡ the exact body you intended
133. Authentication ➡ HMAC ➡ json + secret key + timestamp (UTC) ➡ Each push is only valid for: ➡ the exact body you intended ➡ a small time window
134. Authentication STORE_ID = "5180e2507575e48dd0000001" SECRET_KEY = "1234567890" timestamp = Time.now.utc().to_i json_payload = JSON.generate({ orders: [ { id: 'R1234', status: 'cancelled' } ] }) data = "#{json_payload}@#{timestamp}" SHA1 = OpenSSL::Digest::Digest.new('sha1') hmac = OpenSSL::HMAC.hexdigest(SHA1, SECRET_KEY, data) response = HTTParty.post(‘https://hub.spreecommerce.com/push’, { body: json_payload, headers: { 'X-Hub-Store' => STORE_ID, 'X-Hub-Token' => hmac, 'X-Hub-Timestamp' => timestamp.to_s, 'CONTENT_TYPE' => 'application/json', 'ACCEPT' => 'application/json' } })
135. Authentication STORE_ID = "5180e2507575e48dd0000001" SECRET_KEY = "1234567890" timestamp = Time.now.utc().to_i json_payload = JSON.generate({ orders: [ { id: 'R1234', status: 'cancelled' } ] }) data = "#{json_payload}@#{timestamp}" SHA1 = OpenSSL::Digest::Digest.new('sha1') hmac = OpenSSL::HMAC.hexdigest(SHA1, SECRET_KEY, data) response = HTTParty.post(‘https://hub.spreecommerce.com/push’, { body: json_payload, headers: { 'X-Hub-Store' => STORE_ID, 'X-Hub-Token' => hmac, 'X-Hub-Timestamp' => timestamp.to_s, 'CONTENT_TYPE' => 'application/json', 'ACCEPT' => 'application/json' } })
136. Authentication STORE_ID = "5180e2507575e48dd0000001" SECRET_KEY = "1234567890" timestamp = Time.now.utc().to_i json_payload = JSON.generate({ orders: [ { id: 'R1234', status: 'cancelled' } ] }) data = "#{json_payload}@#{timestamp}" SHA1 = OpenSSL::Digest::Digest.new('sha1') hmac = OpenSSL::HMAC.hexdigest(SHA1, SECRET_KEY, data) response = HTTParty.post(‘https://hub.spreecommerce.com/push’, { body: json_payload, headers: { 'X-Hub-Store' => STORE_ID, 'X-Hub-Token' => hmac, 'X-Hub-Timestamp' => timestamp.to_s, 'CONTENT_TYPE' => 'application/json', 'ACCEPT' => 'application/json' } })
137. Authentication STORE_ID = "5180e2507575e48dd0000001" SECRET_KEY = "1234567890" timestamp = Time.now.utc().to_i json_payload = JSON.generate({ orders: [ { id: 'R1234', status: 'cancelled' } ] }) data = "#{json_payload}@#{timestamp}" SHA1 = OpenSSL::Digest::Digest.new('sha1') hmac = OpenSSL::HMAC.hexdigest(SHA1, SECRET_KEY, data) response = HTTParty.post(‘https://hub.spreecommerce.com/push’, { body: json_payload, headers: { 'X-Hub-Store' => STORE_ID, 'X-Hub-Token' => hmac, 'X-Hub-Timestamp' => timestamp.to_s, 'CONTENT_TYPE' => 'application/json', 'ACCEPT' => 'application/json' } })
138. Authentication STORE_ID = "5180e2507575e48dd0000001" SECRET_KEY = "1234567890" timestamp = Time.now.utc().to_i json_payload = JSON.generate({ orders: [ { id: 'R1234', status: 'cancelled' } ] }) data = "#{json_payload}@#{timestamp}" SHA1 = OpenSSL::Digest::Digest.new('sha1') hmac = OpenSSL::HMAC.hexdigest(SHA1, SECRET_KEY, data) response = HTTParty.post(‘https://hub.spreecommerce.com/push’, { body: json_payload, headers: { 'X-Hub-Store' => STORE_ID, 'X-Hub-Token' => hmac, 'X-Hub-Timestamp' => timestamp.to_s, 'CONTENT_TYPE' => 'application/json', 'ACCEPT' => 'application/json' } })
139. Push support for Spree ➡ Built-in to Spree 2.3
140. Push support for Spree ➡ Built-in to Spree 2.3 ➡ A new ‘core’ gem
141. Push support for Spree ➡ Built-in to Spree 2.3 ➡ A new ‘core’ gem ➡ Disabled by default, activated via preference.
142. Push support for Spree ➡ Built-in to Spree 2.3 ➡ A new ‘core’ gem ➡ Disabled by default, activated via preference. ➡ Will include both Push and Webhooks*
143. Push support for Spree ➡ Built-in to Spree 2.3 ➡ A new ‘core’ gem ➡ Disabled by default, activated via preference. ➡ Will include both Push and Webhooks* ➡ Back-porting all the way to 1.3.x
144. High Availability In push, we trust.
147. Events An interesting change to an object.
148. Events
149. Events “Tom completed an order for 3 t-shirts”
150. Events “Tom completed an order for 3 t-shirts” “Tom’s order has been dispatched”
151. Events “Tom completed an order for 3 t-shirts” “Tom’s order has been dispatched” “A new user called Jane registered”
152. Events “Tom completed an order for 3 t-shirts” “Tom’s order has been dispatched” “A new user called Jane registered” “Jane added a hat to her cart”
153. Events “Tom completed an order for 3 t-shirts” “Tom’s order has been dispatched” “A new user called Jane registered” “Jane added a hat to her cart” “Jane’s cart has be inactive for 5 days”
154. Events “Tom completed an order for 3 t-shirts” “Tom’s order has been dispatched” “A new user called Jane registered” “Jane added a hat to her cart” “Jane’s cart has be inactive for 5 days” “We launched a new Tote product”
155. Events “Tom completed an order for 3 t-shirts” “Tom’s order has been dispatched” “A new user called Jane registered” “Jane added a hat to her cart” “Jane’s cart has be inactive for 5 days” “We launched a new Tote product” “There’s 200 Totes in stock in NYC”
156. Events
157. Events ➡ Created as objects change
158. Events ➡ Created as objects change ➡ Two different ways they can be generated:
159. Events ➡ Created as objects change ➡ Two different ways they can be generated: ➡ created vs. updated - automatic
160. Events ➡ Created as objects change ➡ Two different ways they can be generated: ➡ created vs. updated - automatic ➡ event builder - custom
161. Events ➡ Created as objects change ➡ Two different ways they can be generated: ➡ created vs. updated - automatic ➡ event builder - custom ➡ Connect objects to webhooks*
162. Events: Create Vs. Update
163. Events: Create Vs. Update ➡ The first time the hub receives an object: ➡ object:created ➡ order:created, inventory:created, pirate:created
164. Events: Create Vs. Update ➡ The first time the hub receives an object: ➡ object:created ➡ order:created, inventory:created, pirate:created ➡ Each time a real change is received: ➡ object:updated ➡ product:updated, customer:updated
165. Events: Builder UI
166. Events: Builder UI Easily create powerful event queries using the builder UI.
172. Events trigger webhooks
173. Events trigger webhooks How objects flow through the hub.
174. Events & Webhooks Event Webhook Integration
175. Events & Webhooks Event Webhook Integration shipment:ready /add_shipment
176. Events & Webhooks Event Webhook Integration shipment:ready /add_shipment order:created /add_order
177. Events & Webhooks Event Webhook Integration shipment:ready /add_shipment order:created /add_order shipment:confirm /update_shipment
178. Evented Processing ➡ Decouples processing from the store front. ➡ Enables scability.
179. Webhooks Getting objects out
180. Webhooks - Goals
181. Webhooks - Goals ➡ A set of common patterns for processing events
182. Webhooks - Goals ➡ A set of common patterns for processing events ➡ Well documented
183. Webhooks - Goals ➡ A set of common patterns for processing events ➡ Well documented ➡ Easy to test
184. Webhooks - Goals ➡ A set of common patterns for processing events ➡ Well documented ➡ Easy to test
185. Webhooks - Goals ➡ A set of common patterns for processing events ➡ Well documented ➡ Easy to test ➡ Make integration development even easier
186. Webhooks - Objects
187. Webhooks - Objects Standard naming convention for webhooks:
188. Webhooks - Objects Standard naming convention for webhooks: ➡ add - alerts target system of new object
189. Webhooks - Objects Standard naming convention for webhooks: ➡ add - alerts target system of new object ➡ update - sends object changes
190. Webhooks - Objects Standard naming convention for webhooks: ➡ add - alerts target system of new object ➡ update - sends object changes ➡ get - fetch object changes
191. Webhooks - Objects
192. Webhooks - Objects ➡ add_order ➡ update_order ➡ get_orders Order
193. Webhooks - Objects ➡ add_order ➡ update_order ➡ get_orders Order ➡ add_product ➡ update_product ➡ get_products Product
194. Webhooks - Objects ➡ add_order ➡ update_order ➡ get_orders Order ➡ add_product ➡ update_product ➡ get_products Product ➡ add_customer ➡ update_customer ➡ get_customers Customer
195. Webhooks - Objects ➡ add_order ➡ update_order ➡ get_orders Order ➡ add_product ➡ update_product ➡ get_products Product ➡ add_customer ➡ update_customer ➡ get_customers Customer ➡ add_pirate ➡ update_pirate ➡ get_pirates Pirate
196. Webhooks - Other
197. Webhooks - Other ➡ get_inventory ➡ set_inventory Inventory
198. Webhooks - Other ➡ get_inventory ➡ set_inventory Inventory ➡ send_email ➡ send_sms ➡ create_ticket ➡ add_to_list Comms.
199. Implementing Webhooks ➡ An application capable of receiving a HTTP POST request.
200. Implementing Webhooks ➡ An application capable of receiving a HTTP POST request. ➡ Can use any language or framework.
201. Implementing Webhooks ➡ An application capable of receiving a HTTP POST request. ➡ Can use any language or framework. ➡ Can be standalone, or just a route on a larger app.
202. Implementing Webhooks ➡ An application capable of receiving a HTTP POST request. ➡ Can use any language or framework. ➡ Can be standalone, or just a route on a larger app. ➡ Needs to respond with JSON.
203. Implementing Webhooks ➡ An application capable of receiving a HTTP POST request. ➡ Can use any language or framework. ➡ Can be standalone, or just a route on a larger app. ➡ Needs to respond with JSON. ➡ Can be hosted anywhere.
204. /add_order Webhook { "request_id": "52f367367575e449c3000001", "order": { "id": "R154085346", "number": "R154085346", "channel": "spree", "email": "spree@example.com", "currency": "USD", "placed_on": "2014-02-03T17:29:15.219Z", "updated_at": "2014-02-03T17:29:15.253Z", "status": "complete", "totals": { "item": 100.0, "adjustment": 5.0, "tax": 0.0, POST
205. /add_order Webhook { "request_id": "52f367367575e449c3000001", "order": { "id": "R154085346", "number": "R154085346", "channel": "spree", "email": "spree@example.com", "currency": "USD", "placed_on": "2014-02-03T17:29:15.219Z", "updated_at": "2014-02-03T17:29:15.253Z", "status": "complete", "totals": { "item": 100.0, "adjustment": 5.0, "tax": 0.0, POST
206. /add_order Webhook { "request_id": "52f367367575e449c3000001", "order": { "id": "R154085346", "number": "R154085346", "channel": "spree", "email": "spree@example.com", "currency": "USD", "placed_on": "2014-02-03T17:29:15.219Z", "updated_at": "2014-02-03T17:29:15.253Z", "status": "complete", "totals": { "item": 100.0, "adjustment": 5.0, "tax": 0.0, POST
207. /add_order Webhook { "request_id": "52f367367575e449c3000001", "order": { "id": "R154085346", "number": "R154085346", "channel": "spree", "email": "spree@example.com", "currency": "USD", "placed_on": "2014-02-03T17:29:15.219Z", "updated_at": "2014-02-03T17:29:15.253Z", "status": "complete", "totals": { "item": 100.0, "adjustment": 5.0, "tax": 0.0, POST Response: 200 OK { "request_id": "52f367367575e449c3000001", "summary": "Order imported to Quickbooks", }
208. /add_order Webhook { "request_id": "52f367367575e449c3000001", "order": { "id": "R154085346", "number": "R154085346", "channel": "spree", "email": "spree@example.com", "currency": "USD", "placed_on": "2014-02-03T17:29:15.219Z", "updated_at": "2014-02-03T17:29:15.253Z", "status": "complete", "totals": { "item": 100.0, "adjustment": 5.0, "tax": 0.0, POST Response: 200 OK { "request_id": "52f367367575e449c3000001", "summary": "Order imported to Quickbooks", }
209. /add_order Webhook { "request_id": "52f367367575e449c3000001", "order": { "id": "R154085346", "number": "R154085346", "channel": "spree", "email": "spree@example.com", "currency": "USD", "placed_on": "2014-02-03T17:29:15.219Z", "updated_at": "2014-02-03T17:29:15.253Z", "status": "complete", "totals": { "item": 100.0, "adjustment": 5.0, "tax": 0.0, POST Response: 200 OK { "request_id": "52f367367575e449c3000001", "summary": "Order imported to Quickbooks", }
210. /update_product Webhook { "request_id": "52f367367575e449c3000001", "product": { "id": 58, "parent_id": 11, "name": "Spree T-Shirt", "sku": "SPREE-T-SHIRT-S", "description": "Awesome Spree T-Shirt", "price": 35.0, "cost_price": 22.33, "available_on": "2014-01-29T14:01:28.000Z", "permalink": "spree-tshirt", "meta_description": null, "meta_keywords": null, "shipping_category": "Default", POST
211. /update_product Webhook { "request_id": "52f367367575e449c3000001", "product": { "id": 58, "parent_id": 11, "name": "Spree T-Shirt", "sku": "SPREE-T-SHIRT-S", "description": "Awesome Spree T-Shirt", "price": 35.0, "cost_price": 22.33, "available_on": "2014-01-29T14:01:28.000Z", "permalink": "spree-tshirt", "meta_description": null, "meta_keywords": null, "shipping_category": "Default", POST
212. /update_product Webhook { "request_id": "52f367367575e449c3000001", "product": { "id": 58, "parent_id": 11, "name": "Spree T-Shirt", "sku": "SPREE-T-SHIRT-S", "description": "Awesome Spree T-Shirt", "price": 35.0, "cost_price": 22.33, "available_on": "2014-01-29T14:01:28.000Z", "permalink": "spree-tshirt", "meta_description": null, "meta_keywords": null, "shipping_category": "Default", POST Response: 200 OK { "request_id": "52f367367575e449c3000001", "summary": "Product updated in NetSuite", }
213. /update_product Webhook { "request_id": "52f367367575e449c3000001", "product": { "id": 58, "parent_id": 11, "name": "Spree T-Shirt", "sku": "SPREE-T-SHIRT-S", "description": "Awesome Spree T-Shirt", "price": 35.0, "cost_price": 22.33, "available_on": "2014-01-29T14:01:28.000Z", "permalink": "spree-tshirt", "meta_description": null, "meta_keywords": null, "shipping_category": "Default", POST Response: 200 OK { "request_id": "52f367367575e449c3000001", "summary": "Product updated in NetSuite", }
214. /update_product Webhook { "request_id": "52f367367575e449c3000001", "product": { "id": 58, "parent_id": 11, "name": "Spree T-Shirt", "sku": "SPREE-T-SHIRT-S", "description": "Awesome Spree T-Shirt", "price": 35.0, "cost_price": 22.33, "available_on": "2014-01-29T14:01:28.000Z", "permalink": "spree-tshirt", "meta_description": null, "meta_keywords": null, "shipping_category": "Default", POST Response: 200 OK { "request_id": "52f367367575e449c3000001", "summary": "Product updated in NetSuite", }
215. Webhook: Parameters { "request_id": "52f367367575e449c3000001", "order": {}, "parameters": { "quickbooks.access_token": "qyprd1vQF...", "quickbooks.access_secret": "xTrT6dckbY...", "quickbooks.realm": "1231232" } } POST
216. Webhook: Parameters { "request_id": "52f367367575e449c3000001", "order": {}, "parameters": { "quickbooks.access_token": "qyprd1vQF...", "quickbooks.access_secret": "xTrT6dckbY...", "quickbooks.realm": "1231232" } } POST
217. Webhook: Parameters { "request_id": "52f367367575e449c3000001", "order": {}, "parameters": { "quickbooks.access_token": "qyprd1vQF...", "quickbooks.access_secret": "xTrT6dckbY...", "quickbooks.realm": "1231232" } } POST Response: 200 OK { "request_id": "52f367367575e449c3000001", "summary": "Order imported to Quickbooks", }
218. /get_customers Webhook { "request_id": "52f367367575e449c3000001", "parameters": { "since": "2014-02-03T17:29:00.000Z } } POST
219. /get_customers Webhook { "request_id": "52f367367575e449c3000001", "parameters": { "since": "2014-02-03T17:29:00.000Z } } POST
220. /get_customers Webhook { "request_id": "52f367367575e449c3000001", "parameters": { "since": "2014-02-03T17:29:00.000Z } } POST Response: 200 OK { "request_id": "52f367367575e449c3000001", "customers": [ { "id": 1, "email": "brian@spreecommerce.com" }, { "id": 2, "first_name": "Sean", "last_name": "Schofield" ], "parameters": { "since": "2014-02-03T17:35:00.000Z" } }
221. /get_customers Webhook { "request_id": "52f367367575e449c3000001", "parameters": { "since": "2014-02-03T17:29:00.000Z } } POST Response: 200 OK { "request_id": "52f367367575e449c3000001", "customers": [ { "id": 1, "email": "brian@spreecommerce.com" }, { "id": 2, "first_name": "Sean", "last_name": "Schofield" ], "parameters": { "since": "2014-02-03T17:35:00.000Z" } }
222. /get_customers Webhook { "request_id": "52f367367575e449c3000001", "parameters": { "since": "2014-02-03T17:29:00.000Z } } POST Response: 200 OK { "request_id": "52f367367575e449c3000001", "customers": [ { "id": 1, "email": "brian@spreecommerce.com" }, { "id": 2, "first_name": "Sean", "last_name": "Schofield" ], "parameters": { "since": "2014-02-03T17:35:00.000Z" } }
223. /add_order Webhook { "request_id": "52f367367575e449c3000001", "order": { "id": "R154085346", "number": "R154085346", "channel": "spree", "email": "spree@example.com", "currency": "USD", "placed_on": "2014-02-03T17:29:15.219Z", "updated_at": "2014-02-03T17:29:15.253Z", "status": "complete", "totals": { "item": 100.0, "adjustment": 5.0, "tax": 0.0, POST
224. /add_order Webhook { "request_id": "52f367367575e449c3000001", "order": { "id": "R154085346", "number": "R154085346", "channel": "spree", "email": "spree@example.com", "currency": "USD", "placed_on": "2014-02-03T17:29:15.219Z", "updated_at": "2014-02-03T17:29:15.253Z", "status": "complete", "totals": { "item": 100.0, "adjustment": 5.0, "tax": 0.0, POST Response: 500 Error { "request_id": "52f367367575e449c3000001", "summary": "Order import failed for NetSuite", }
225. /add_order Webhook { "request_id": "52f367367575e449c3000001", "order": { "id": "R154085346", "number": "R154085346", "channel": "spree", "email": "spree@example.com", "currency": "USD", "placed_on": "2014-02-03T17:29:15.219Z", "updated_at": "2014-02-03T17:29:15.253Z", "status": "complete", "totals": { "item": 100.0, "adjustment": 5.0, "tax": 0.0, POST Response: 500 Error { "request_id": "52f367367575e449c3000001", "summary": "Order import failed for NetSuite", }
226. /add_order Webhook { "request_id": "52f367367575e449c3000001", "order": { "id": "R154085346", "number": "R154085346", "channel": "spree", "email": "spree@example.com", "currency": "USD", "placed_on": "2014-02-03T17:29:15.219Z", "updated_at": "2014-02-03T17:29:15.253Z", "status": "complete", "totals": { "item": 100.0, "adjustment": 5.0, "tax": 0.0, POST Response: 500 Error { "request_id": "52f367367575e449c3000001", "summary": "Order import failed for NetSuite", }
227. Authentication ➡ With each webhook, the hub includes the following headers:
228. Authentication ➡ With each webhook, the hub includes the following headers: ➡ X-Hub-Store ➡ Unique store identifier
229. Authentication ➡ With each webhook, the hub includes the following headers: ➡ X-Hub-Store ➡ Unique store identifier ➡ X-Hub-Token ➡ Pre-shared secret to identify the hub is sending the POST.
230. endpoint_base https://github.com/spree/endpoint_base
231. endpoint_base ➡ Supports both Sinatra & Rails endpoints, & provides:
232. endpoint_base ➡ Supports both Sinatra & Rails endpoints, & provides: ➡ Authentication
233. endpoint_base ➡ Supports both Sinatra & Rails endpoints, & provides: ➡ Authentication ➡ Helper methods & variables
234. endpoint_base ➡ Supports both Sinatra & Rails endpoints, & provides: ➡ Authentication ➡ Helper methods & variables ➡ @payload & @config
235. endpoint_base ➡ Supports both Sinatra & Rails endpoints, & provides: ➡ Authentication ➡ Helper methods & variables ➡ @payload & @config ➡ Response DSL
236. endpoint_base ➡ Supports both Sinatra & Rails endpoints, & provides: ➡ Authentication ➡ Helper methods & variables ➡ @payload & @config ➡ Response DSL ➡ Rendering
237. The Hub in Action
238. Handling Failures Retry Patterns
239. Retry Patterns: Failure hub
240. Retry Patterns: Failure hub Order PUSH order:created
241. Retry Patterns: Failure hub Netsuite Order PUSH order:created
242. Retry Patterns: Failure hub /add_order 500: fail! Netsuite Order PUSH order:created
243. /add_order Webhook { "request_id": "52f367367575e449c3000001", "order": { "id": "R154085346", "number": "R154085346", "channel": "spree", "email": "spree@example.com", "currency": "USD", "placed_on": "2014-02-03T17:29:15.219Z", "updated_at": "2014-02-03T17:29:15.253Z", "status": "complete", "totals": { "item": 100.0, "adjustment": 5.0, "tax": 0.0, POST
244. /add_order Webhook { "request_id": "52f367367575e449c3000001", "order": { "id": "R154085346", "number": "R154085346", "channel": "spree", "email": "spree@example.com", "currency": "USD", "placed_on": "2014-02-03T17:29:15.219Z", "updated_at": "2014-02-03T17:29:15.253Z", "status": "complete", "totals": { "item": 100.0, "adjustment": 5.0, "tax": 0.0, POST Response: 500 Error { "request_id": "52f367367575e449c3000001", "summary": "SKU ‘ROR-123’ is invalid.", }
245. Retry Patterns: Back-off hub Netsuite Order PUSH order:created
246. Retry Patterns: Back-off hub /add_order 500: fail! /add_order 200: success Netsuite /add_order 500: fail! /add_order 500: fail! Order PUSH order:created
247. Retry Patterns: Back-off hub /add_order 500: fail! /add_order 200: success Netsuite /add_order 500: fail! /add_order 500: fail! Order PUSH
248. Retry Patterns: Auto-recovery hub Netsuite Order PUSH order:created
249. Retry Patterns: Auto-recovery hub Netsuite Order PUSH order:created 500: fail! /add_order 500: fail! /add_order
250. Retry Patterns: Auto-recovery hub Netsuite Order PUSH order:created Order PUSH 500: fail! /add_order 500: fail! /add_order *
251. Retry Patterns: Auto-recovery hub /add_order Netsuite Order PUSH order:created Order PUSH 200: success 500: fail! /add_order 500: fail! /add_order *
252. Retry Patterns: No retry hub Netsuite Order PUSH order:created
253. Retry Patterns: No retry hub order:created 500: fail! Netsuite Order PUSH order:created
265. Macros Object converters
266. Macros ➡ Embedded javascript functions
267. Macros ➡ Embedded javascript functions ➡ Get applied to the body of a webhook
268. Macros ➡ Embedded javascript functions ➡ Get applied to the body of a webhook ➡ before it’s sent to the integration
269. Macros ➡ Embedded javascript functions ➡ Get applied to the body of a webhook ➡ before it’s sent to the integration ➡ Has access to:
270. Macros ➡ Embedded javascript functions ➡ Get applied to the body of a webhook ➡ before it’s sent to the integration ➡ Has access to: ➡ entire body (including parameters).
271. Macros ➡ Embedded javascript functions ➡ Get applied to the body of a webhook ➡ before it’s sent to the integration ➡ Has access to: ➡ entire body (including parameters). ➡ underscore.js, helper methods, more.
272. Communications Use Case: “I want to send a user an email after they complete an order” ➡ Object: Order ➡ Event: order:created ➡ Webhook: POST /send_email
273. Marcos - Use Case { "order": { "id": "R154085346", "status": "complete", "channel": "spree", "email": "spree@example.com", "currency": "USD", "placed_on": "2014-02-03T17:29:15.219Z", "totals": { }, "line_items": [ { "name": "Spree T-Shirt", "sku": "SPREE-T-SHIRT", "external_ref": "", "quantity": 2, Order Object
274. Marcos - Use Case { "order": { "id": "R154085346", "status": "complete", "channel": "spree", "email": "spree@example.com", "currency": "USD", "placed_on": "2014-02-03T17:29:15.219Z", "totals": { }, "line_items": [ { "name": "Spree T-Shirt", "sku": "SPREE-T-SHIRT", "external_ref": "", "quantity": 2, Order Object { "request_id": "52f367367575e449c3000001", "email": { "to": "spree@example.com", "from": "someone@spreecommerce.com", "subject": "Order R123456 was shipped!", "template": "order_shipped", "variables": { "customer_name": "John Smith", "order_total": "100.00", "order_tracking": "XYZ123" } } } /send_email webhook
275. Marcos - Use Case { "order": { "id": "R154085346", "status": "complete", "channel": "spree", "email": "spree@example.com", "currency": "USD", "placed_on": "2014-02-03T17:29:15.219Z", "totals": { }, "line_items": [ { "name": "Spree T-Shirt", "sku": "SPREE-T-SHIRT", "external_ref": "", "quantity": 2, Order Object { "request_id": "52f367367575e449c3000001", "email": { "to": "spree@example.com", "from": "someone@spreecommerce.com", "subject": "Order R123456 was shipped!", "template": "order_shipped", "variables": { "customer_name": "John Smith", "order_total": "100.00", "order_tracking": "XYZ123" } } } /send_email webhook
276. Macro - Example var email = { variables: {} }; email.to = request.order.email; email.from = find_param('mandrill.order_confirimation_from'); email.template = find_param('mandrill.order_confirimation_template'); email.variables.order_number = request.order.number; email.variables.shipping_first_name = request.order.shipping_address.firstname; email.variables.shipping_last_name = request.order.shipping_address.lastname; email.variables.total = Number(payload.order.totals.order).toFixed(2); _.each(request.order.line_items, function(item){ email.variables.line_item_rows += '<tr><td>' + item.name + '</td>\ <td>' + item.quantity + '</td>\ <td>$' + Number(item.price).toFixed(2) + '</td></tr>'; }); request.email = email;
277. Macro - Example var email = { variables: {} }; email.to = request.order.email; email.from = find_param('mandrill.order_confirimation_from'); email.template = find_param('mandrill.order_confirimation_template'); email.variables.order_number = request.order.number; email.variables.shipping_first_name = request.order.shipping_address.firstname; email.variables.shipping_last_name = request.order.shipping_address.lastname; email.variables.total = Number(payload.order.totals.order).toFixed(2); _.each(request.order.line_items, function(item){ email.variables.line_item_rows += '<tr><td>' + item.name + '</td>\ <td>' + item.quantity + '</td>\ <td>$' + Number(item.price).toFixed(2) + '</td></tr>'; }); request.email = email;
278. Macro - Example var email = { variables: {} }; email.to = request.order.email; email.from = find_param('mandrill.order_confirimation_from'); email.template = find_param('mandrill.order_confirimation_template'); email.variables.order_number = request.order.number; email.variables.shipping_first_name = request.order.shipping_address.firstname; email.variables.shipping_last_name = request.order.shipping_address.lastname; email.variables.total = Number(payload.order.totals.order).toFixed(2); _.each(request.order.line_items, function(item){ email.variables.line_item_rows += '<tr><td>' + item.name + '</td>\ <td>' + item.quantity + '</td>\ <td>$' + Number(item.price).toFixed(2) + '</td></tr>'; }); request.email = email;
279. Macro - Example var email = { variables: {} }; email.to = request.order.email; email.from = find_param('mandrill.order_confirimation_from'); email.template = find_param('mandrill.order_confirimation_template'); email.variables.order_number = request.order.number; email.variables.shipping_first_name = request.order.shipping_address.firstname; email.variables.shipping_last_name = request.order.shipping_address.lastname; email.variables.total = Number(payload.order.totals.order).toFixed(2); _.each(request.order.line_items, function(item){ email.variables.line_item_rows += '<tr><td>' + item.name + '</td>\ <td>' + item.quantity + '</td>\ <td>$' + Number(item.price).toFixed(2) + '</td></tr>'; }); request.email = email;
280. Macro - Example var email = { variables: {} }; email.to = request.order.email; email.from = find_param('mandrill.order_confirimation_from'); email.template = find_param('mandrill.order_confirimation_template'); email.variables.order_number = request.order.number; email.variables.shipping_first_name = request.order.shipping_address.firstname; email.variables.shipping_last_name = request.order.shipping_address.lastname; email.variables.total = Number(payload.order.totals.order).toFixed(2); _.each(request.order.line_items, function(item){ email.variables.line_item_rows += '<tr><td>' + item.name + '</td>\ <td>' + item.quantity + '</td>\ <td>$' + Number(item.price).toFixed(2) + '</td></tr>'; }); request.email = email;
281. Macro - Example var email = { variables: {} }; email.to = request.order.email; email.from = find_param('mandrill.order_confirimation_from'); email.template = find_param('mandrill.order_confirimation_template'); email.variables.order_number = request.order.number; email.variables.shipping_first_name = request.order.shipping_address.firstname; email.variables.shipping_last_name = request.order.shipping_address.lastname; email.variables.total = Number(payload.order.totals.order).toFixed(2); _.each(request.order.line_items, function(item){ email.variables.line_item_rows += '<tr><td>' + item.name + '</td>\ <td>' + item.quantity + '</td>\ <td>$' + Number(item.price).toFixed(2) + '</td></tr>'; }); request.email = email;
282. Learn More
283. spreecommerce.com/docs/hub/ Hub Guides & Test tool
303. Learn More: Talk to us! Sean, Josh, Brad, Mike & Andrew
304. SpreeConf: Whisky
305. SpreeConf: Whisky http://www.whiskyblender.com/b.php?code=WB35828
307. Questions? Answers?