Event Subscription

Kibo eCommerce generates an event each time a user or application performs create, update, or delete operations. In Dev Center, a developer can configure external applications to subscribe to events, such as when a new product is created or an existing order is updated. Using the Kibo eCommerce API, applications can retrieve specific event notifications for a given tenant, catalog, or site. Because all events occur at the site level, if a tenant-level action occurs, such as the creation of a new customer account, the system triggers the event notification for every site associated with the tenant.

Retrieve Events

Use the Event Pull API resource to retrieve events.

Push Subscriptions

A subscription to an event triggers the push service that a tenant or external application uses to receive immediate notifications when actions associated with the events occur in Kibo eCommerce. Authorized applications can subscribe to receive notifications when the associated event occurs for the sites the application can access. When a subscribed event occurs in a tenant or site the subscribing application can access, the eventing system creates a notification and relays it to the endpoint configured for the external application.

The push notification message body is sent as an HTTP POST, commonly referred to as a "webhook". The webhook POST body content includes limited event payload information that the subscriber uses to call the Kibo eCommerce API and retrieve additional information about the event. For example, if an application receives a notification that a new order was created, the application uses the data in the notification response to call the Kibo eCommerce API and views the details of the newly created order. The entityId value returned in the response payload typically represents the ID of the object for the application to retrieve. To version events, maintain security, and limit payload size, the event payload does not return the object itself, such as an order or product definition. For more information about individual events and which objects the entityId value represents, see Event Reference.

The event notification object sent by an HTTP POST webhook contains the following information:

For example, if an application subscribes to the product.updated event and the same product is updated 50 times, the event payloads would contain the following:

The response header includes the API context information. If the event notification delivery service fails for a specific subscriber for 24 hours, all notifications for the subscriber are disabled. To re-enable push notifications, the subscriber must log in to Dev Center and verify the event configuration.

In Dev Center, an application can subscribe to events. When the specified event occurs, it triggers an event that is routed to a configured endpoint. For example, if you subscribed to the product.created event for your application, the application triggers a push notification every time a new product is created in the associated tenant store.

Push Notification Delivery

When an application subscribes to an event, Kibo eCommerce services send push notifications to the configured API endpoint. When an event push notification delivery fails, the redelivery service attempts to deliver the notification for 24 consecutive hours according to the defined retry schedule.

After the 24-hour delivery failure interval is met, the redelivery service terminates the process and the event status updates to "undeliverable." To receive events, the application must use the Event Pull resource in the Kibo eCommerce API.

Pull Notifications

After an event occurs, application developers use the Kibo eCommerce API to create pull notifications, which display the details of a specific event, including the notification details, or a collection of events. When retrieving events using the API, developers can use the request header to specify the tenant, master catalog, catalog, or site information. Alternatively, developers can specify the application authentication information, which automatically determines the tenant or site context for which the application can view events. Using this method, developers can search and filter across all tenants and sites the application can access. For example, developers can filter the results to display only product.created events for a specific tenant. The event object retrieved with an HTTP GET pull contains the following information:

If the event notification delivery service fails for 24 hours, applications use the event pull operations to view events not delivered using push notifications for 30 days.

Behaviors

To call the API to retrieve additional information about an event, the external application must have the behavior associated with the event. For example, if an application subscribes to the cart.updated event and a push notification is sent to the application, the application must have the “Cart Read” behavior to call the API to view the updated shopping cart details based on the entityId value supplied in the event response body.

Event Reference

Applications can subscribe to or retrieve any of the following events using the Kibo eCommerce API:

Event Category Entity ID Represents Event Description
Application Application ID application.installed

An application was installed in a tenant. You can only subscribe an application to this event on the Configuration Events tab.

application.uninstalled The application was removed from a tenant. You can only subscribe an application to this event on the Configuration Events tab.
application.upgraded A newer version of the application was installed in a tenant. You can only subscribe an application to this event on the Configuration Events tab.
application.enabled The application was enabled in a tenant. You can only subscribe an application to this event on the Configuration Events tab.
application.disabled The application was disabled for a tenant. You can only subscribe an application to this event on the Configuration Events tab.
Cart Cart ID cart.created The first item was added to a new cart.
cart.updated The contents of a defined cart were updated.
cart.deleted A cart was deleted. The system deletes a cart when a shopper attempts to retrieve an expired cart, or when an anonymous shopper with an active cart logs in and merges the anonymous cart with the user's cart.
Category Category ID category.created A new product category was created.
category.updated The properties of a defined product category were updated. This does not include event notifications when a client adds a product to or removes a product from a category.
category.deleted A defined product category was deleted.
Credit Credit ID credit.created A store credit or gift card was created for a customer account.
credit.updated The properties of a store credit or gift card were updated. This includes notifications when a client associates the credit with a customer account and notifications when a shopper spends all or part of the credit balance.
credit.deleted A store credit or gift card was deleted.
Customer Account Customer account ID customeraccount.created A customer account was created in the tenant. Because customer accounts are stored at the tenant level, an event notification occurs for each site associated with the tenant.
customeraccount.updated The properties of a defined customer account were updated.
customeraccount.deleted A defined customer account was deleted.
Customer Segment Customer Segment ID customersegment.created A new customer segment was created.
customersegment.updated The properties of a defined customer segment were updated. This does not include notifications for when a client adds customer accounts to or removes customer accounts from a customer segment.
customersegment.customeradded A customer account was added to the defined customer segment.
customersegment.customerremoved A customer account was removed from the defined customer segment.
customersegment.deleted A defined customer segment was deleted.
Discount Discount ID discount.created A new discount or coupon was created.
discount.updated The properties of a defined discount or coupon were updated. This does not include notifications when a shopper redeems a discount.
discount.expired A defined discount or coupon expired.
discount.deleted A defined discount or coupon was deleted.
Email Email ID email.requested An email was requested.
Facet Facet ID facet.created A new facet was created.
facet.updated A defined facet was updated.
facet.deleted A defined facet was deleted.
Location Location Code location.created A new physical location was configured for a tenant environment.
location.updated One or more properties of a defined physical location are updated in the tenant environment.
location.deleted A defined physical location was deleted from the tenant environment.
Location Type Code locationtype.created A new location type was defined used to group locations.
locationtype.updated One or more properties of a location type were updated, or locations were added to or removed from the location type.
locationtype.deleted A defined location type was deleted. You cannot delete locations types with associated locations.
Order Order ID order.opened A new order was accepted. This generally occurs after a successful checkout process. However, if you have order validation integrations installed, such as a fraud detection integration, this occurs after the order passes the review process.
order.fulfilled The order was shipped to the customer or an in-store pickup was created for fulfillment.
order.closed An order was closed after it was fully paid and fulfilled.
order.cancelled A defined order was cancelled.
order.updated One or more properties of a defined order was updated.
order.pendingreview A defined order is pending further review.
order.abandoned A defined order was abandoned.
Return ID return.cancelled A defined return was cancelled.
return.closed The return was closed after a return replacement or refund was issued.
return.opened A return was created.
return.updated One or more properties of a defined return are updated.
return.rejected A return is marked as rejected in Kibo eCommerce.
Shipment ID shipment.fulfilled A shipment of packages associated with an order fulfillment was shipped to the shopper.
  Product Product Code producttype.created A new product type was created in any master catalog. The system triggers an event for each site that features the new product in its associated catalog.
producttype.deleted A defined product type was deleted.
producttype.updated One or more properties of a defined product type were updated.
product.coderenamed A defined product code was renamed.
product.created A new product was created in any master catalog. The system triggers an event for each site that features the new product in its associated catalog.
product.updated One or more properties of a defined product, product bundle, or a variation of a defined product were updated.
product.deleted A defined product was deleted.
productdraft.created An update was made to a product definition in draft mode.
productdraft.deleted A product definition was deleted in a catalog associated with a master catalog that uses the "Pending" product publishing mode.
productdraft.discarded Draft changes to a product definition were discarded.
productdraft.published Draft changes to a product definition were published to a live site.
productdraft.updated One or more properties of a product definition were updated in an existing draft.
productinventory.instock A product previously out of stock returns to a site's active inventory.
productinventory.outofstock The active inventory stock of a product was depleted at the specified site.
productinventory.updated The number of a product was updated in active inventory stock at the specified site.
wishlist.created A new wish list was created and associated with the customer account.
wishlist.deleted A wish list associated with the customer account was deleted.
wishlist.updated One or more properties of a wish list were updated, or items are added to or removed from a wish list associated with the customer account.
Search Search Settings searchsettings.updated One or more search setting properties were updated.
Site Site ID site.created A new site was created.
site.cloned A defined site was cloned.
site.updated One or more properties of a defined site were updated.
site.deleted A defined site was deleted.
Tenant Tenant ID tenant.updated One or more properties of the defined tenant were updated.
tenant.deleted A defined tenant was deleted.