Tracked event catalog

SHOPIFY_TRACKED_TOPICS is the source of truth for webhook registration and subscriber eligibility. The current allowlist contains 39 topics across 12 resource modules.

Topic-to-module mapping

Module	Tracked Shopify topics	Handler / service	Snapshot table
Orders	orders/create, orders/updated, orders/paid, orders/cancelled, orders/fulfilled, orders/partially_fulfilled, orders/delete, orders/edited	ShopifyOrdersHandler / ShopifyOrdersService	shopify_orders
Checkouts	checkouts/create, checkouts/update, checkouts/delete	ShopifyCheckoutsHandler / ShopifyCheckoutsService	shopify_checkouts
Carts	carts/create, carts/update	ShopifyCartsHandler / ShopifyCartsService	shopify_carts
Products	products/create, products/update, products/delete	ShopifyProductsHandler / ShopifyProductsService	shopify_products
Customers	customers/create, customers/update, customers/delete, customers/enable, customers/disable	ShopifyCustomerHandler / ShopifyCustomersService	shopify_customers
Customer groups	customer_groups/create, customer_groups/update, customer_groups/delete	ShopifyCustomerGroupsHandler / ShopifyCustomerGroupsService	shopify_customer_groups
Payment terms	payment_terms/create, payment_terms/update, payment_terms/delete	ShopifyPaymentTermsHandler / ShopifyPaymentTermsService	shopify_payment_terms
Refunds	refunds/create	ShopifyRefundsHandler / ShopifyRefundsService	shopify_refunds
Selling plan groups	selling_plan_groups/create, selling_plan_groups/update, selling_plan_groups/delete	ShopifySellingPlanGroupsHandler / ShopifySellingPlanGroupsService	shopify_selling_plan_groups
Returns	returns/approve, returns/cancel, returns/close, returns/decline, returns/reopen, returns/request	ShopifyReturnsHandler / ShopifyReturnsService	shopify_returns
Reverse deliveries	reverse_deliveries/attach_deliverable	ShopifyReverseDeliveriesHandler / ShopifyReverseDeliveriesService	shopify_reverse_deliveries
Reverse fulfillment orders	reverse_fulfillment_orders/dispose	ShopifyReverseFulfillmentOrdersHandler / ShopifyReverseFulfillmentOrdersService	shopify_reverse_fulfillment_orders

Allowlist enforcement points

The same tuple is reused in three places:

1. shopify.webhooks.WEBHOOK_TOPICS registers only these topics with Shopify.
2. subscriber.router creates handler mappings only for normalized versions of these topics.
3. parse_shopify_event() rejects any normalized event type outside the tuple.

Tests assert that every allowlisted topic has a handler, parses with a minimal object payload, maps to the expected resource table, and round-trips between slash and dot notation.

Examples explicitly rejected by tests include fulfillments/create and app/uninstalled.

Operation semantics

The parser sets is_deleted = true only when the text after the first slash is exactly delete.

This means:

• orders/delete, checkouts/delete, products/delete, customers/delete, customer_groups/delete, payment_terms/delete, and selling_plan_groups/delete soft-delete their snapshots.
• Returns operations such as cancel, close, and decline remain active snapshots with is_deleted = false; their business state remains inside the payload.
• reverse_fulfillment_orders/dispose also remains is_deleted = false under the generic parser.

Parsing depth by event family

Event family	Structural validation	Field-level typed parsing	Stored parsed_payload
Customers create/update/delete	Yes	Yes, existing customer dataclass parsers	Dataclass converted to JSON dictionary
Customers enable/disable	Yes	No	Original payload
All other 10 modules plus customer groups	Yes	No	Original payload

The handler/service split makes future module-specific parsers straightforward: each service can call a dedicated parser while keeping storage and retry behavior unchanged.