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. To receive these events, create a subscription through the Admin API. Subscribing through the SCAYLE Panel is not available yet. For the general producer webhook flow, see Manage Producer Webhooks in the Admin API.
First, list the events that the storefront-api producer offers. The name of each returned event is the value you pass as eventName when you create a subscription:
Then, create a subscription with the event, the shop country, and your endpoint URL:
The response returns the created subscription, including its id. Keep the id to update or delete the subscription later. To see the subscriptions you already created, list the subscriptions for the producer.
| Field | Meaning |
|---|---|
eventName | Required. The event this subscription delivers: product-created, product-updated, or product-deleted. |
url | Required. Your endpoint that receives the webhook. |
target.shopCountryId | Required. The shop country this subscription covers. It is the only property target accepts for this producer. |
enabled | Defaults to true. Set to false to create the subscription without receiving events yet. |
rpm | Maximum requests per minute SCAYLE sends to your endpoint. |
email | Address SCAYLE notifies about the subscription, for example when it is suspended. |
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 request for each event and shop country you want to receive.
