@spree/docs 0.1.181 → 0.1.183

package/dist/developer/core-concepts/events.md

@@ -1,644 +1,151 @@
 ---
 title: Events
-description: Spree's event system — publish and subscribe to lifecycle events from orders, products, and users to trigger background jobs and integrations.
+description: Reacting to things that happen in Spree — an order placed, a payment taken, stock running out — without modifying core code.
 ---
 
-import { Since } from '/snippets/since.mdx';
-
-
 ## Overview
 
-Spree includes a powerful event system that allows you to react to various actions happening in your store. When something happens (an order is completed, a product is created, etc.), Spree publishes an event that your code can subscribe to and handle.
-
-This pattern enables loose coupling between components and makes it easy to:
-
-- Send email notifications when orders are placed
-- Sync data with external services when products change
-- Log audit trails for compliance
-- Trigger webhooks to notify third-party systems
-- Update caches when inventory changes
-
-## How Events Work
-
-Spree's event system provides a clean API through:
+Something happens in a store — an order is placed, a payment clears, a product sells out — and you want something else to happen: notify a warehouse, post to a channel, update a spreadsheet.
 
-1. **`Spree::Events`** - The main module for publishing and subscribing to events
-2. **`Spree::Subscriber`** - Base class for creating event subscribers
-3. **`Spree::Publishable`** - Concern that enables models to publish events
-
-When an event is published, all matching subscribers are notified. By default, subscribers run asynchronously via background jobs to avoid blocking the main request.
+Events are how you attach that behaviour without editing Spree. Spree announces what happened; your code decides what to do about it.
 
 ```mermaid
-flowchart TB
-    subgraph Spree Application
-        A[Model Action] --> B[publish_event]
-        B --> C[Event Serializer]
-        C --> D[Spree::Events]
-    end
-
-    subgraph Event Adapter
-        D --> E[Find Matching Subscribers]
-        E --> F{Async?}
-        F -->|Yes| G[Queue Background Job]
-        F -->|No| H[Execute Immediately]
-    end
-
-    subgraph Subscribers
-        G --> I[SubscriberJob]
-        I --> J[Your Subscriber]
-        H --> J
-        J --> K[Send Email]
-        J --> L[Sync External Service]
-        J --> M[Update Cache]
-        J --> N[Trigger Webhook]
-    end
-```
-
-## Creating a Subscriber
-
-The fastest path is the generator — it creates the class, a spec stub, and registers the subscriber in `config/initializers/spree.rb` (the step that's easy to forget):
-
-
-```bash Spree CLI (Docker)
-spree generate subscriber OrderCompleted order.completed
-```
-
-```bash Without Spree CLI
-bin/rails g spree:subscriber OrderCompleted order.completed
-```
-
-
-Or create the class by hand in `app/subscribers/`, inheriting from `Spree::Subscriber`:
-
-```ruby app/subscribers/order_completed_subscriber.rb
-class OrderCompletedSubscriber < Spree::Subscriber
-  subscribes_to 'order.completed'
-
-  def handle(event)
-    order_id = event.payload['id']
-    order = Spree::Order.find_by_prefix_id(order_id)
-    return unless order
-
-    # Your custom logic here
-    ExternalService.notify_order_placed(order)
-  end
-end
+flowchart LR
+    Action["Order is placed"] --> Event["order.placed"]
+    Event --> Sub["Your subscriber<br/>(in-app)"]
+    Event --> Hook["Webhook<br/>(external system)"]
 ```
 
-Then register it in an initializer — subscribers are not auto-discovered (see [Registering Subscribers](#registering-subscribers)):
+There are two ways to listen, and which you want depends on where your code lives:
 
-```ruby config/initializers/spree.rb
-Rails.application.config.after_initialize do
-  Spree.subscribers << OrderCompletedSubscriber
-end
-```
-
-### Subscriber DSL
-
-The `Spree::Subscriber` class provides a clean DSL for declaring subscriptions:
-
-```ruby
-class MySubscriber < Spree::Subscriber
-  # Subscribe to a single event
-  subscribes_to 'order.completed'
-
-  # Subscribe to multiple events
-  subscribes_to 'order.completed', 'order.canceled', 'order.resumed'
-
-  # Subscribe to all events matching a pattern
-  subscribes_to 'order.*'  # All order events
-  subscribes_to '*.*'      # All events (use sparingly!)
-
-  # Run synchronously instead of via background job
-  subscribes_to 'order.completed', async: false
-end
-```
-
-### Handling Multiple Events
-
-When subscribing to multiple events, use the `on` DSL to route events to specific methods:
-
-```ruby app/subscribers/order_audit_subscriber.rb
-class OrderAuditSubscriber < Spree::Subscriber
-  subscribes_to 'order.completed', 'order.canceled', 'order.resumed'
-
-  on 'order.completed', :log_order_completed
-  on 'order.canceled', :log_order_canceled
-  on 'order.resumed', :log_order_resumed
-
-  private
-
-  def log_order_completed(event)
-    create_audit_log(event, 'completed')
-  end
-
-  def log_order_canceled(event)
-    create_audit_log(event, 'canceled')
-  end
-
-  def log_order_resumed(event)
-    create_audit_log(event, 'resumed')
-  end
-
-  def create_audit_log(event, action)
-    AuditLog.create!(
-      resource_type: 'Spree::Order',
-      resource_id: event.payload['id'],
-      action: action,
-      occurred_at: event.created_at
-    )
-  end
-end
-```
-
-## Working with Events
-
-### Event Object
-
-When your subscriber receives an event, you get a `Spree::Event` object with:
-
-```ruby
-def handle(event)
-  event.id         # => "550e8400-e29b-41d4-a716-446655440000" (UUID)
-  event.name       # => "order.completed"
-  event.store_id   # => 1 (ID of the store where the event originated)
-  event.payload    # => { "id" => 1, "number" => "R123456", ... }
-  event.metadata   # => { "spree_version" => "<spree_version>" }
-  event.created_at # => Time when event was published
-
-  # Helper methods
-  event.store        # => Spree::Store instance (lazy loaded)
-  event.resource_type # => "order" (extracted from name)
-  event.action        # => "completed" (extracted from name)
-end
-```
-
-### Finding the Record
-
-The payload contains serialized attributes, not the actual record. To get the record:
-
-```ruby
-def handle(event)
-  record_id = event.payload['id']
-  record = Spree::Order.find_by_prefix_id(record_id)
-  return unless record
-
-  # Work with the record
-end
-```
-
-> **WARNING:** For destroy events, the record no longer exists in the database. Use the payload data instead, or capture what you need before deletion.
-
-## Available Events
-
-### Lifecycle Events
-
-Models that include `Spree::Publishable` and call `publishes_lifecycle_events` automatically publish:
-
-| Event Pattern | Description |
-|---------------|-------------|
-| `{model}.created` | Record was created |
-| `{model}.updated` | Record was updated |
-| `{model}.deleted` | Record was deleted |
-
-For example, `Spree::Price` publishes `price.created`, `price.updated`, and `price.deleted`.
-
-Models with lifecycle events enabled include: `Order`, `Payment`, `Price`, `Shipment`, `Variant`, `LineItem`, `StockItem`, and many others.
-
-### Order Events
-
-| Event | Description |
-|-------|-------------|
-| `order.created` | Order was created |
-| `order.updated` | Order was updated |
-| `order.completed` | Order checkout completed |
-| `order.canceled` | Order was canceled |
-| `order.resumed` | Canceled order was resumed |
-| `order.paid` | Order is fully paid |
-| `order.shipped` | All order shipments are shipped |
-
-### Shipment Events
-
-| Event | Description |
-|-------|-------------|
-| `shipment.created` | Shipment was created |
-| `shipment.updated` | Shipment was updated |
-| `shipment.shipped` | Shipment was shipped |
-| `shipment.canceled` | Shipment was canceled |
-| `shipment.resumed` | Shipment was resumed |
-
-### Payment Events
-
-| Event | Description |
-|-------|-------------|
-| `payment.created` | Payment was created |
-| `payment.updated` | Payment was updated |
-| `payment.paid` | Payment was completed |
-
-### Price Events
-
-| Event | Description |
-|-------|-------------|
-| `price.created` | Price was created |
-| `price.updated` | Price was updated |
-| `price.deleted` | Price was deleted |
-
-### User Events
-
-| Event | Description |
-|-------|-------------|
-| `user.created` | User was created |
-| `user.updated` | User was updated |
-| `user.deleted` | User was deleted |
-
-When `Spree.admin_user_class` differs from `Spree.user_class`, admin users publish the equivalent `admin.*` events (see the Admin Events table below).
-
-### Admin Events
-
-| Event | Description |
-|-------|-------------|
-| `admin.created` | Admin user was created |
-| `admin.updated` | Admin user was updated |
-| `admin.deleted` | Admin user was deleted |
-
-### Product Events
-
-| Event | Description |
-|-------|-------------|
-| `product.activated` | Product status changed to active |
-| `product.archived` | Product status changed to archived |
-| `product.out_of_stock` | Product has no stock left for any variant |
-| `product.back_in_stock` | Product was out of stock and now has stock again |
-
-## Publishing Custom Events
-
-You can publish custom events from anywhere in your application:
-
-### From a Model
-
-Models including `Spree::Publishable` can use `publish_event`:
-
-```ruby
-class Spree::Order < Spree.base_class
-  def mark_as_fraudulent!
-    update!(fraudulent: true)
-    publish_event('order.marked_fraudulent')
-  end
-end
-```
+| | Use it when |
+|---|---|
+| **[Webhooks](webhooks.md)** | The thing reacting is a separate system — a Next.js app, an ERP, an automation tool |
+| **Subscribers** | The reaction belongs inside the Spree application itself |
 
-### From Anywhere
+If you're building a headless storefront, **webhooks are almost certainly what you want**. Subscribers are for when you're running Spree as your own application and want to add behaviour to it.
 
-Use `Spree::Events.publish` directly:
+## What Spree announces
 
-```ruby
-Spree::Events.publish(
-  'inventory.low_stock',
-  { variant_id: variant.id, quantity: variant.total_on_hand }
-)
-```
+Most records announce their own lifecycle:
 
-## Event Serializers
+| Event | When |
+|---|---|
+| `<resource>.created` | A record is created |
+| `<resource>.updated` | It changes |
+| `<resource>.deleted` | It's removed |
 
-Event payloads are generated using the same [Store API V3 serializers](../../api-reference/store-api/introduction.md) used by the REST API. This means webhook payloads and API responses share the same schema, making it easy to reuse types in your integrations.
+Those exist for orders, carts, products, variants, customers, payments, fulfillments, returns, media, price changes and more.
 
-### How Serializers Work
+On top of that, meaningful business moments get their own events:
 
-When a model publishes an event, Spree looks for a V3 serializer class matching the model name:
+| Event | Meaning |
+|---|---|
+| `order.placed` | A customer completed checkout |
+| `order.paid` | Payment is settled in full |
+| `order.canceled` | The order was cancelled |
+| `order.shipped` / `order.delivered` | Everything has shipped / arrived |
+| `payment.completed` / `payment.voided` | A payment succeeded / was released |
+| `fulfillment.shipped` / `fulfillment.canceled` | A parcel went out / was stood down |
+| `product.out_of_stock` / `product.back_in_stock` | Availability flipped |
+| `return.received` / `return.refunded` | A return arrived / was refunded |
+| `import.completed` / `export.completed` | Bulk work finished |
 
-- `Spree::Order` → `Spree::Api::V3::OrderSerializer`
-- `Spree::Product` → `Spree::Api::V3::ProductSerializer`
-- `Spree::Payment` → `Spree::Api::V3::PaymentSerializer`
+The distinction matters when choosing what to listen for. `order.updated` fires whenever anything about an order changes — including an admin editing a note. `order.placed` fires once, when a customer actually bought something. Sending a confirmation email on the wrong one is how customers receive nine copies.
 
-For STI models (e.g., `Spree::Exports::Products`), the serializer lookup walks up the class hierarchy until it finds a match (e.g., → `Spree::Api::V3::ExportSerializer`).
+## What an event carries
 
-If no serializer is found, a minimal fallback payload is returned:
+An event carries the record it's about, serialized:
 
 ```json
-{ "id": "prod_86Rf07xd4z", "created_at": "2025-01-15T10:00:00Z", "updated_at": "2025-01-15T10:30:00Z" }
+{
+  "id": "or_86Rf07xd4z",
+  "number": "R123456789",
+  "status": "placed",
+  "payment_status": "paid",
+  "total": "135.60",
+  "email": "customer@example.com"
+}
 ```
 
-### Built-in Serializers
-
-Spree includes V3 serializers for all core models in [`api/app/serializers/spree/api/v3/`](https://github.com/spree/spree/tree/main/api/app/serializers/spree/api/v3):
-
-| Serializer | Model |
-|------------|-------|
-| `OrderSerializer` | Orders with totals, statuses, nested line items, fulfillments, payments, addresses |
-| `ProductSerializer` | Products with pricing, stock status, availability |
-| `PaymentSerializer` | Payments with amounts, states, nested payment method and source |
-| `FulfillmentSerializer` | Fulfillments (shipments) with tracking, nested delivery method and delivery rates |
-| `LineItemSerializer` | Line items with quantity, pricing, nested option values |
-| `VariantSerializer` | Variants with SKU, pricing, nested option values |
-| `PriceSerializer` | Prices with amounts, currency, price list |
-| ... | [And many more](https://github.com/spree/spree/tree/main/api/app/serializers/spree/api/v3) |
+IDs are the same prefixed IDs the API uses, so you can take an ID out of an event and fetch the full record without translating anything.
 
-### Payload Context
+## Reacting in another system
 
-Event serializers receive specific context parameters that control what data is included:
+Point a webhook at your endpoint and subscribe it to the events you care about. That's covered fully in [Webhooks](webhooks.md) — including signature verification, which you should not skip.
 
-- **`store`** — Prefers the resource's store (e.g., `order.store`), falls back to `Spree::Current.store`
-- **`currency`** — Uses `Spree::Current.currency` (with full fallback chain)
-- **`user: nil`** — Events never include user-specific pricing
-- **`includes: []`** — Conditional associations are not included in event payloads
+## Reacting inside Spree
 
-This means event payloads contain the same top-level attributes and unconditional associations as API responses, but conditional associations (like product variants, media, or custom fields) are excluded.
-
-### Overriding Event Serializers
-
-To customize the payload for existing events, create a custom V3 serializer and configure it via [dependencies](../customization/dependencies.md):
-
-```ruby app/serializers/my_app/order_serializer.rb
-module MyApp
-  class OrderSerializer < Spree::Api::V3::OrderSerializer
-    # Add custom attributes
-    attribute :loyalty_points do |order|
-      (order.total.to_f * 10).to_i
-    end
-
-    attribute :custom_field do |order|
-      order.custom_field
-    end
-  end
-end
-```
+A subscriber is a small class that names the events it wants and does something when one arrives.
 
-```ruby config/initializers/spree.rb
-Spree.api.order_serializer = 'MyApp::OrderSerializer'
+```bash
+bin/rails g spree:subscriber OrderPlaced order.placed
 ```
 
-> **WARNING:** When overriding serializers, make sure to include all attributes that webhooks and subscribers depend on. Removing attributes may break integrations.
-
-### Serializers for Custom Models
+The generator writes the class, a test, and — the step that's easy to forget — registers it.
 
-If you add a custom model that publishes events, create a V3 serializer:
+```ruby app/subscribers/order_placed_subscriber.rb
+class OrderPlacedSubscriber < Spree::Subscriber
+  subscribes_to 'order.placed'
 
-```ruby app/models/spree/subscription.rb
-module Spree
-  class Subscription < Spree.base_class
-    publishes_lifecycle_events
-
-    def renew!
-      update!(renewed_at: Time.current)
-      publish_event('subscription.renewed')
-    end
-  end
-end
-```
+  def handle(event)
+    order = Spree::Order.find_by_prefix_id(event.payload['id'])
+    return unless order
 
-```ruby app/serializers/spree/api/v3/subscription_serializer.rb
-module Spree
-  module Api
-    module V3
-      class SubscriptionSerializer < BaseSerializer
-        typelize plan_name: :string, status: :string,
-                 user_id: [:string, nullable: true],
-                 renewed_at: [:string, nullable: true],
-                 expires_at: [:string, nullable: true]
-
-        attributes :plan_name, :status,
-                   renewed_at: :iso8601, expires_at: :iso8601,
-                   created_at: :iso8601, updated_at: :iso8601
-
-        attribute :user_id do |subscription|
-          subscription.user&.prefixed_id
-        end
-      end
-    end
+    WarehouseClient.new.submit(order)
   end
 end
 ```
 
-Models without a matching serializer will use a minimal fallback payload containing only `id`, `created_at`, and `updated_at`.
+A subscriber can listen to several events, or to a whole family:
 
-## Registering Subscribers
-
-Subscribers are not auto-discovered — every subscriber must be registered explicitly, regardless of where the class lives. Add it to the `Spree.subscribers` array in `config/initializers/spree.rb` (or any initializer):
-
-```ruby config/initializers/spree.rb
-Rails.application.config.after_initialize do
-  Spree.subscribers << CustomSubscriber
-end
+```ruby
+subscribes_to 'order.placed', 'order.canceled'
+subscribes_to 'order.*'
 ```
 
-To remove a built-in subscriber:
+Subscribers must be registered — they aren't discovered automatically, because a subscriber that starts running because of where its file sits is hard to reason about:
 
 ```ruby config/initializers/spree.rb
 Rails.application.config.after_initialize do
-  Spree.subscribers.delete(Spree::ExportSubscriber)
+  Spree.subscribers << OrderPlacedSubscriber
 end
 ```
 
-## Synchronous vs Asynchronous
+### Subscribers run in the background
 
-By default, subscribers run asynchronously via a background job. This prevents slow subscriber code from blocking HTTP requests.
+By default a subscriber runs as a background job, so a slow API call in your code doesn't slow down the customer's checkout — and a failure doesn't roll back their order.
 
-For critical operations that must complete before the request finishes, use synchronous mode:
+That's almost always what you want. If you genuinely need to run inside the same transaction, you can ask to:
 
 ```ruby
-class CriticalOrderHandler < Spree::Subscriber
-  subscribes_to 'order.completed', async: false
-
-  def handle(event)
-    # This runs immediately, blocking the request
-  end
-end
+subscribes_to 'order.placed', async: false
 ```
 
-> **WARNING:** Use synchronous subscribers sparingly. They can significantly slow down your application if the handler code is slow or makes external API calls.
+> **WARNING:** A synchronous subscriber runs while the customer waits, and an exception in it can fail their checkout. Reserve it for work that must be atomic with the order, and keep it fast.
 
-## Temporarily Disabling Events
+## Publishing your own events
 
-You can disable event publishing temporarily:
+Anything in your own code can announce something, and subscribers and webhooks treat it like any built-in event:
 
 ```ruby
-Spree::Events.disable do
-  # Events published in this block won't trigger subscribers
-  order.complete!
-end
-```
-
-This is useful for:
-- Data migrations where you don't want to trigger side effects
-- Test setup where subscribers would interfere
-- Bulk operations where individual events would be too noisy
-
-## Testing Subscribers
-
-### Testing Event Handling
-
-```ruby spec/subscribers/order_completed_subscriber_spec.rb
-require 'spec_helper'
-
-RSpec.describe OrderCompletedSubscriber do
-  let(:order) { create(:completed_order_with_totals) }
-  let(:event) do
-    Spree::Event.new(
-      name: 'order.completed',
-      payload: order.event_payload
-    )
-  end
-
-  describe '#handle' do
-    it 'notifies external service' do
-      expect(ExternalService).to receive(:notify_order_placed).with(order)
-      described_class.new.handle(event)
-    end
-  end
-end
+order.publish_event('order.flagged_for_review')
 ```
 
-### Testing Event Publishing
-
-Stub `Spree::Events.publish` to assert an event is published:
-
-```ruby
-it 'publishes order.completed event' do
-  expect(Spree::Events).to receive(:publish).with(
-    'order.completed',
-    hash_including('id' => order.id)
-  )
-
-  order.complete!
-end
-```
-
-The `lifecycle events` shared examples in `spree/core/lib/spree/testing_support/lifecycle_events.rb` cover the standard `created`/`updated`/`deleted` lifecycle events.
-
-## Best Practices
-
-
-  - **Keep handlers fast** — Move slow operations to background jobs. Subscribers should do minimal work and delegate heavy lifting.
-
-  - **Handle missing records** — Always check if the record exists before processing. It may have been deleted between event publish and handler execution.
-
-  - **Be idempotent** — Design handlers to be safely re-run. Events might be delivered more than once in edge cases.
-
-  - **Use specific patterns** — Subscribe to specific events rather than wildcards when possible. This makes code easier to understand and debug.
-
-
-## Example: Inventory Alert Subscriber
-
-Here's a complete example of a subscriber that sends alerts when inventory is low:
-
-```ruby app/subscribers/inventory_alert_subscriber.rb
-class InventoryAlertSubscriber < Spree::Subscriber
-  subscribes_to 'stock_item.updated'
-
-  LOW_STOCK_THRESHOLD = 10
-
-  def handle(event)
-    stock_item = find_stock_item(event)
-    return unless stock_item
-    return unless low_stock?(event)
-
-    send_low_stock_alert(stock_item)
-  end
-
-  private
-
-  def find_stock_item(event)
-    Spree::StockItem.find_by_prefix_id(event.payload['id'])
-  end
-
-  def low_stock?(event)
-    event.payload['count_on_hand'].to_i < LOW_STOCK_THRESHOLD
-  end
-
-  def send_low_stock_alert(stock_item)
-    InventoryMailer.low_stock_alert(
-      variant: stock_item.variant,
-      stock_location: stock_item.stock_location,
-      count_on_hand: stock_item.count_on_hand
-    ).deliver_later
-  end
-end
-```
-
-> **NOTE:** A lifecycle event payload carries only the resource's current serialized state, not its previous values. If you need a true "just dropped below the threshold" check that compares the count before and after the change, record or cache the prior count separately rather than reading it from the event payload.
-
-## Custom Event Adapters
-
-Spree's event system uses an adapter pattern, making it possible to swap the underlying event infrastructure. By default, Spree uses [`ActiveSupport::Notifications`](https://api.rubyonrails.org/classes/ActiveSupport/Notifications.html), but you can create custom adapters for other backends like Kafka, RabbitMQ, or Redis Pub/Sub.
-
-### Configuring a Custom Adapter
-
-Set your adapter class in an initializer:
-
-```ruby config/initializers/spree.rb
-Spree.events_adapter_class = 'MyApp::Events::KafkaAdapter'
-```
-
-### Creating a Custom Adapter
-
-Inherit from `Spree::Events::Adapters::Base` and implement the required methods:
-
-```ruby app/models/my_app/events/kafka_adapter.rb
-module MyApp
-  module Events
-    class KafkaAdapter < Spree::Events::Adapters::Base
-      def publish(event_name, payload, metadata = {})
-        event = build_event(event_name, payload, metadata)
-
-        # Publish to Kafka
-        kafka_producer.produce(
-          event.to_json,
-          topic: "spree.#{event_name}"
-        )
-
-        event
-      end
-
-      def subscribe(pattern, subscriber, options = {})
-        registry.register(pattern, subscriber, options)
-      end
-
-      def unsubscribe(pattern, subscriber)
-        registry.unregister(pattern, subscriber)
-      end
-
-      def activate!
-        @kafka_producer = Kafka.new(
-          seed_brokers: ENV['KAFKA_BROKERS']
-        ).producer
-      end
-
-      def deactivate!
-        @kafka_producer&.shutdown
-      end
-
-      private
-
-      attr_reader :kafka_producer
-    end
-  end
-end
-```
+Useful when your own domain has moments worth reacting to — a fraud check completing, an approval granted.
 
-### Base Class Interface
+## Guidance
 
-The `Spree::Events::Adapters::Base` class defines the required interface:
+**Listen for the specific event.** `order.placed` rather than `order.updated` with a status check.
 
-| Method | Description |
-|--------|-------------|
-| `publish(event_name, payload, metadata)` | Publish an event, return `Spree::Event` |
-| `subscribe(pattern, subscriber, options)` | Register a subscriber for a pattern |
-| `unsubscribe(pattern, subscriber)` | Remove a subscriber |
-| `activate!` | Called during application initialization |
-| `deactivate!` | Called during shutdown |
+**Assume events can arrive more than once.** A retry after a network blip can redeliver. Make handlers safe to run twice — check whether you've already acted before acting.
 
-The base class also provides helper methods:
-- `build_event(name, payload, metadata)` - Creates a `Spree::Event` instance
-- `invoke_subscribers(event)` - Finds and invokes matching subscribers (internally calling `registry.subscriptions_for`)
-- `registry` - Access to the `Spree::Events::Registry` instance
+**Don't chain long sequences of subscribers.** When one event triggers a subscriber that triggers another, working out what happened after the fact becomes archaeology. Prefer one handler that does the sequence.
 
-> **INFO:** See `Spree::Events::Adapters::ActiveSupportNotifications` for a complete reference implementation.
+**Keep failures contained.** A subscriber that raises shouldn't take down anything else. Handle your own errors and log them.
 
-## Related Documentation
+## Related
 
-- [Events Tutorial](../tutorial/events.md) - Hands-on, step-by-step walkthrough of building an event subscriber
-- [Webhooks](webhooks.md) - HTTP callbacks for external integrations
-- [Webhooks & Events Reference](../../api-reference/webhooks-events.md) - Catalog of event and webhook payloads
-- [Customization Quickstart](../customization/quickstart.md) - Overview of all customization options
-- [Decorators](../customization/decorators.md) - When to use decorators vs events
-- [Checkout Flow](carts.md) - Using events in checkout customization
+- [Webhooks](webhooks.md) — reacting from outside Spree
+- [Orders](orders.md) — the order lifecycle these events describe
+- [Imports & Exports](imports-exports.md) — completion events for bulk work