spree-events-webhooks

Spree Events + Webhooks

Spree has two layered systems for reacting to lifecycle events. Both subscribe to the same events; what differs is the delivery target.

System	Lives	Use for
Subscribers	Ruby code in your Rails app	Sync to your own ERP, send transactional email, update analytics, invalidate caches
Webhooks	HTTPS POSTs to external URLs	Third-party integrations, partner systems, customer-built apps

You pick a subscriber when you are the consumer. You pick a webhook when another system is the consumer.

Part 1: Subscribers (in-process)

Spree::Order.complete!
  ↓
order.publish_event('order.completed', payload)
  ↓
Spree::Subscribers each receive the event
  ↓
Your subscriber: sync to ERP, send email, etc.

Automatic lifecycle events (*.created, *.updated, *.deleted) fire after the transaction commits — if the write fails, those subscribers never run. Custom events published via publish_event(...) (including order.completed) are dispatched at the call site, which may be inside an open transaction: sync subscribers run inline, and async subscriber jobs are enqueued immediately — possibly before the commit. Don't assume the surrounding write has committed.

Writing a subscriber

Use the generator (Spree 5.5+) — it creates the class, a spec stub, and handles registration:

spree generate subscriber OrderComplete order.completed   # native: bin/rails g spree:subscriber …
# flags: --sync (async: false), --skip-spec

Or by hand: put the class anywhere autoloadable (e.g. app/subscribers/), then register it in an initializer — subscribers are NOT auto-discovered, and an unregistered subscriber is a silent no-op:

# config/initializers/spree.rb
Rails.application.config.after_initialize do
  Spree.subscribers << OrderCompleteSubscriber
end

# app/subscribers/order_complete_subscriber.rb
class OrderCompleteSubscriber < Spree::Subscriber
  subscribes_to 'order.completed'

  def handle(event)
    order_id = event.payload['id']
    ExternalErp.sync_order(order_id)
  end
end