Event Notifications Overview

Notifications are payloads of data that are provided as the order progresses through fulfillment stages, which can be sent to a JSON endpoint or custom application. These payloads are triggered automatically when any “event” happens in the fulfillment process - such as when an order is created or changes status. These events may originate from either the user interface or API – notifications are triggered by any appropriate action regardless of where it happens. Because these 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.

The table in this guide lists some of the most common notifications, identifies the events that trigger them, and links to schemas detailing the parameters that are received in the payloads. These notifications are listed by “topics,” or groups of notifications with related purposes.

Endpoint Configuration

For more information about subscribing custom applications to listen for events, refer to the Application Development documentation and Webhooks API documentation. These resources include technical guidelines for how the eventing process works, how to configure your endpoint, and schemas for each individual event. These configuration best practices are listed below. 

Duplicate Prevention

Kibo expects a 200 OK success response to be returned from within 45 seconds of sending the notification. If no success response is received during that time or if an HTTP status error message is received, the notification will be placed in a queue to be resent every minute or so (the actual timing will vary based on the size of the queue). The notification will continue to be resent until either the success response is received or the notification expires after 14 days. 

Due to this process, the endpoint may sometimes receive duplicates of notifications. To avoid saturation with a large number of duplicates, it is recommended to configure the endpoint with duplicate prevention.

Out-Of-Order Events

It is sometimes possible for notifications of different topics to be received out of order. While Kibo should always send notifications of the same topic in the order of the process flow, notifications from different topic groups are not guaranteed to be sent in any particular order. For instance, if a shipment event triggers both a Shipment Status and a Shipment Workflow notification, it is not known which will be received first by the endpoint. Thus, it is also advised to configure the endpoint to be capable of receiving out-of-order notifications to avoid any problems that may be caused by expecting these different notifications in a strict order.

Retry Behavior

It is also important to know that Kibo uses backoff behavior when re-queueing failed notifications. If there is a server outage or other issue preventing notifications from successfully sending, the system will retry several times. The first time the notification fails, there will be a five minute delay before attempting to send it again. The second time it fails, there will be a one hour delay. If it continues to fail, the amount of time between attempts will increase to the point of 24 hours before making the final attempt. If it still cannot go through, the notification will not be tried again.

This means that if orders are placed during a short-term outage that lasts a few hours, the notifications for those orders will eventually come through once the outage is resolved.

Event Notification Formatting

Notifications will always consist of limited event payload information that you can then use to retrieve additional information about that event. 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 - just the IDs. 

For instance, when you receive an order.updated notification you can use the order ID in that payload to then make a GET call to the Order API and retrieve the full order data.

Notification Fields

Notification objects contain the following basic information to describe events. Some may provide additional details depending on the context, such as old and new shipment states or the reason that a change was made. 

  • eventID: A unique identifier for the event.
  • topic: The type of event that occurred, such as product.created.
  • entityID: Identifies the object for which the action occurred, such as a product code or order ID or shipment number.
  • timestamp: The date-time at which the event occurred.
  • correlationID: An identifier used by Kibo to track API requests across different services in the data logs.
  • isTest: Boolean indicator that identifies whether the event was sent as part of a test.
  • extendedProperties: Detailed metadata not provided by all notifications. This is a list of key:value string pairs, which vary depending on what information is being provided.

Notification Topics

Notifications are organized by topics, which are buckets of one or more notifications associated with a particular object such as orders or shipments. 

Event CategoryEntity ID RepresentsEventDescription
CartCart IDcart.createdThe first item was added to a new cart.
cart.updatedThe contents of a defined cart were updated.
cart.deletedA 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.
CategoryCategory IDcategory.createdA new product category was created.
category.updatedThe 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.deletedA defined product category was deleted.
CreditCredit IDcredit.createdA store credit or gift card was created for a customer account.
credit.updatedThe 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.deletedA store credit or gift card was deleted.
Customer AccountCustomer Account IDcustomeraccount.createdA 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.updatedThe properties of a defined customer account were updated.
customeraccount.deletedA defined customer account was deleted.
Customer SegmentCustomer Segment IDcustomersegment.createdA new customer segment was created.
customersegment.updatedThe 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.customeraddedA customer account was added to the defined customer segment.
customersegment.customerremovedA customer account was removed from the defined customer segment.
customersegment.deletedA defined customer segment was deleted.
B2B AccountB2B Account IDb2baccount.statuschangedA B2B account changed its status. This is triggered when an account moves into any of the following states: ACTIVE, DISABLED, or PENDING APPROVAL.
DiscountDiscount IDdiscount.createdA new discount or coupon was created.
discount.updatedThe properties of a defined discount or coupon were updated. This does not include notifications when a shopper redeems a discount.
discount.expiredA defined discount or coupon expired.
discount.deletedA defined discount or coupon was deleted.
EmailEmail IDemail.requestedAn email was requested.
FacetFacet IDfacet.createdA new facet was created.
facet.updatedA defined facet was updated.
facet.deletedA defined facet was deleted.
InventoryReservation IDinventory.cartitemallocatedInventory was successfully allocated for reservation.
Cart IDinventory.cartpendingitemcreatedItems were overallocated and a pending item was successfully created.
LocationLocation Codelocation.createdA new physical location was configured for a tenant environment.
location.updatedOne or more properties of a defined physical location are updated in the tenant environment.
location.deletedA defined physical location was deleted from the tenant environment.
Location Type Codelocationtype.createdA new location type was defined used to group locations.
locationtype.updatedOne or more properties of a location type were updated, or locations were added to or removed from the location type.
locationtype.deletedA defined location type was deleted. You cannot delete locations types with associated locations.
OrderOrder IDorder.abandonedA defined order was abandoned.
order.addresschangedAn order's address was changed.
order.cancelledA defined order was cancelled.
order.erroredAn order experienced an error.
order.closedAn order was closed after it was fully paid and fulfilled.
order.fulfilledThe order was shipped to the customer or an in-store pickup was created for fulfillment.
order.importedA historic order was imported.
order.openedA 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.pendingreviewA defined order is pending further review.
order.savedAn order was updated and saved.
order.updatedOne or more properties of a defined order was updated.
Return IDreturn.cancelledA defined return was cancelled.
return.closedThe return was closed after a return replacement or refund was issued.
return.openedA return was created.
return.updatedOne or more properties of a defined return are updated.
return.rejectedA return is marked as rejected.
Payment IDpayment.authorizedAn order payment was authorized.
payment.capturedAn order payment was captured. If both an authorization and a capture were performed at the same time, it is considered to be a capture event.
payment.creditedAn order payment was credited.
payment.refundedAn order payment was refunded. Appeasements are also considered to be payment.refunded events.
payment.transactionerrorAn order payment experienced a transaction error.
payment.voidedAn order payment was voided.
  ProductProduct Codeproducttype.createdA 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.deletedA defined product type was deleted.
producttype.updatedOne or more properties of a defined product type were updated.
product.coderenamedA defined product code was renamed.
product.createdA 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.updatedOne or more properties of a defined product, product bundle, or a variation of a defined product were updated.
product.deletedA defined product was deleted.
productdraft.createdAn update was made to a product definition in draft mode.
productdraft.deletedA product definition was deleted in a catalog associated with a master catalog that uses the "Pending" product publishing mode.
productdraft.discardedDraft changes to a product definition were discarded.
productdraft.publishedDraft changes to a product definition were published to a live site.
productdraft.updatedOne or more properties of a product definition were updated in an existing draft.
productinventory.instockA product previously out of stock returns to a site's active inventory.
productinventory.outofstockThe active inventory stock of a product was depleted at the specified site.
productinventory.updatedThe number of a product was updated in active inventory stock at the specified site.
ReservationReservation IDreservation.deallocatedAn inventory reservation was deallocated.
reservation.expiredAn inventory reservation expired.
ReturnReturn IDreturn.authorizedA return was authorized.
return.cancelledA return was cancelled.
return.closedA return was processed and closed.
return.openedA new return was created.
return.rejectedA return was rejected instead of authorized.
return.updatedA return was updated.
ShipmentShipment IDshipment.adjustedAn adjustment was made at the shipment level.
shipment.itemadjustedAn adjustment was made at the shipment item level, such as when the item requirements are changed to make the shipment fulfillable by the assigned location.
shipment.itemscanceledA shipment line item was canceled.
shipment.itemsdeclinedA shipment line item was declined.
shipment.itemsrejectedA shipment line item was rejected.
Shipment StatusShipment IDshipment.statuschangedA shipment changed its status. This is triggered when a shipment moves into any of the following states: READY, REASSIGNED, BACKORDER, CANCELLED, FULFILLED, or CUSTOMER_CARE.
Shipment WorkflowShipment IDshipment.workflowstatechangedA shipment changed its workflow state. While this may be related to shipment status events, this is not triggered by the status change itself. Instead, it is triggered by the shipment moving to another step in the fulfillment workflow (such as ACCEPTED_SHIPMENT or PRE_ACCEPT_SHIPMENT, depending on the implementation).
SearchSearch Settingssearchsettings.updatedOne or more search setting properties were updated.
SiteSite IDsite.createdA new site was created.
site.clonedA defined site was cloned.
site.updatedOne or more properties of a defined site were updated.
site.deletedA defined site was deleted.
SubscriptionsSubscription IDsubscription.statuschangedA subscription changed status to Active, Paused, Cancelled, or Errored.
subscription.activatedA subscription has been activated.
subscription.cancelledA subscription was cancelled.
subscription.erroredA subscription experienced an error.
subscription.pausedA subscription was paused.
subscription.paymentupdatedA subscription's payment method was updated.
TenantTenant IDtenant.createdA new tenant was created.
tenant.deletedA defined tenant was deleted.
tenant.expiringA defined tenant is expiring.
tenant.hard_deletedA defined tenant was hard deleted from the system.
tenant.updatedOne or more properties of the defined tenant were updated.
tenant.userloginA user logged in to a defined tenant.