Product Events
SCAYLE can notify your systems through webhooks when a product changes. There are two sources of product events, and they answer different questions.
| Admin API Product Events | Storefront Product Events | |
|---|---|---|
| Tells you | A product changed in the SCAYLE backend, the source of truth. | A product change is now live and visible to shoppers through the Storefront API. |
| Fires | When the change is made. | After the change is indexed and visible in Storefront API responses. |
| Scope | Global. One subscription covers all shop countries. | Per shop country. Each event carries its shopCountryId. |
| Granularity | Granular. Separate events for master data, variants, prices, and availability. | Coarse. Three lifecycle events that reflect the published product. |
| Events | product-updated, product-master-updated, product-deleted, product-variant-deleted, product-variant-stock-updated, product-variant-prices-updated, product-variant-availability-updated. | product-created, product-updated, product-deleted. |
Two differences stand out. Admin API events are granular, so you get a separate event for a price change, an availability change, or a variant removal. Storefront events are coarse, so any of those changes arrives as a single product-updated. Admin API events also have no product-created, while Storefront events do, because a product first becomes visible to shoppers at index time.
Which one should you use
Pick the source that matches what your system needs to react to.
- Use Admin API Product Events when you act on backend changes as soon as they happen, regardless of whether the change is live for shoppers yet. For example, syncing an internal system with the SCAYLE source data.
- Use Storefront Product Events when you act on what shoppers can actually see. For example, refreshing an external search index, a product feed, or a cache that mirrors the storefront. These events fire once the change is indexed, which is the same moment it appears in Storefront API responses.
You can subscribe to both if your systems need each view.
Subscribing
Admin API and Storefront product events use different subscription mechanisms.
Admin API Product Events
Admin API Product Events use the standard webhook subscriptions. You create them through the Admin API:
- Get all webhook events
- List subscriptions
- Get a subscription
- Create a subscription
- Update a subscription
- Delete a subscription
Storefront Product Events
Storefront Product Events are delivered as webhooks under the producer storefront-api. Each subscription covers one event for one shop country. SCAYLE pre-creates these subscriptions, so you configure an existing one rather than creating it yourself. Subscribing through the SCAYLE Panel is not available yet.
First, list the subscriptions for the producer and find the id for the event and shop country you want:
Then, update that subscription with your endpoint URL and enable it:
| Field | Meaning |
|---|---|
eventName | The event this subscription delivers: product-created, product-updated, or product-deleted. |
url | Your endpoint that receives the webhook. |
target.shopCountryId | The shop country this subscription covers. |
enabled | Set to true to start receiving events. |
rpm | Maximum requests per minute SCAYLE sends to your endpoint. |
email | Contact address for the subscription. |
isInternal | false for external consumers. |
auth | Optional basic auth credentials SCAYLE sends with each request. |
customHeaders | Optional headers SCAYLE adds to each request. |
Repeat the update for each event and shop country you want to receive.
