What problem does it solve?
Provides clear instructions and best practices to receive, acknowledge, and reliably process real-time webhook notifications sent by Tray, removing ambiguity about payload format, retry behavior, and event routing so developers can keep external systems in sync.
Core Features & Use Cases
- Scope-aware routing: Covers product, product_price, product_stock, variant, variant_price, variant_stock, order, customer and store_config events and how to route by scope_name + act.
- Payload handling: Explains that Tray sends application/x-www-form-urlencoded POST payloads and shows how to parse seller_id, scope_id, scope_name and act.
- Retry and resilience: Details Tray's non-200 retry behavior, progressive backoff, 20-day retention, and recommends immediate HTTP 200 responses, asynchronous processing, and idempotency handling.
- MultiCD and payments: Notes MultiCD behavior for stock events and clarifies payment notification flow embedded in order objects.
- Operational best practices: Recommends seller_id validation, logging for audit/debug, query-after-notify for canonical data, and queue-based background processing.
Quick Start
Use the tray-webhooks skill to generate an endpoint that returns HTTP 200 immediately, parses application/x-www-form-urlencoded payloads, routes events by scope_name and act, and enqueues them for asynchronous processing.
