Storefront Product Events
SCAYLE emits Storefront product events whenever a product change becomes live and visible to shoppers through the Storefront API. Subscribe to these events to keep an external system in sync with the published catalog, for example a search index, a feed, or a cache.
These events reflect the storefront state. If you need backend changes the moment they happen, see Admin API Product Events. For the comparison between the two, see Product Events.
Available Events
All events are scoped to a shop country.
| Event | Trigger |
|---|---|
product-created | A product becomes available in a shop country for the first time. |
product-updated | An existing product's data changes, for example attributes, images, variants, prices, or stock. |
product-deleted | A product is no longer available in a shop country, for example after it is deleted or deactivated. |
Actions That Trigger Events
Events follow the changes you make through the SCAYLE Panel or the Admin API:
- You create a product and it becomes active in a shop country:
product-created - You change product master data, attributes, images, or category assignments:
product-updated - You add, change, or remove variants:
product-updated - A variant's price or stock changes:
product-updated - You delete a product, deactivate it, or remove it from a shop country:
product-deleted
Events do not fire at the moment you save a change. SCAYLE processes product data in regular indexing runs, and the event goes out once your change is indexed. This is also the moment the change becomes visible in Storefront API responses.
Before sending product-updated, SCAYLE compares the new product data with the previous state and only sends the event when the data differs. Saving a product without changing anything does not trigger an event.
Subscribing
Storefront product events are delivered as add-on webhooks under the producer storefront-api. Each subscription covers one event for one shop country, and you configure it through the Admin API. See Product Events for the subscription steps and request examples.
Payload
Every event you receive has this shape:
The payload is self-describing: it carries the event type, when the event occurred, the product identifiers, and the shop country, so you can process it without relying on any surrounding delivery metadata.
| Field | Meaning |
|---|---|
type | The event type: product-created, product-updated, or product-deleted. |
occurredAt | When the event was emitted, as an RFC 3339 / ISO 8601 timestamp in UTC. This is the moment the change was indexed and became visible in the Storefront API, not the moment you saved it. |
payload.id | The product ID. |
payload.referenceKey | The product reference key. |
meta.shopCountryId | The shop country the product belongs to. |
Request Headers
Each webhook request you receive includes the following headers.
| Header | Value | Meaning |
|---|---|---|
x-producer | storefront-api | Identifies the source of the event. |
x-external | false | Always false for Storefront product events sent by SCAYLE. |
Example: From Event to Product Data
The event is a notification, not a full product snapshot. Use payload.id to fetch the current product data from the Storefront API.
A product-updated event arrives at your endpoint:
Fetch the product from the Storefront API. The meta.shopCountryId from the event is the shopId query parameter:
The response contains the current product state:
Product Response
Consuming Events
Storefront product events follow the same delivery behavior as all SCAYLE webhooks, so the general guidance on duplicates and ordering applies. For more details, see Webhooks.
One point is specific to product events:
Fetch, do not derive. The event tells you that a product changed. Fetch the current state from the Storefront API instead of reconstructing it from the event payload.
