About Data Events

Data events let backend code respond when items in a site's collections change. Wix triggers a data event after an item is created, updated, or deleted, and your handler receives the item and details about the change. For example, you can use data events to:

• Notify a team when a visitor submits a new item.
• Update a related collection, such as a count of listings per agent.
• Sync changes with an external system.
• Keep an audit log of changes.

Which collections trigger data events

Only user-created collections trigger data events. Wix app collections, such as those that Wix Stores adds, and collections from an external database never trigger data events. To respond to changes in a business solution's data, handle that solution's own events in a Backend Events extension, such as the Wix eCommerce Order Created event.

In a user-created collection, changes trigger events whether they come from site code or from an edit in the CMS dashboard.

A handler receives the events for all user-created collections on the site. To respond to changes in one collection only, check event.entity.dataCollectionId in the handler.

Available data events

The items module of the Data API includes these events:

• Data Item Created: Triggered when an item is inserted.
• Data Item Updated: Triggered when an item is updated or patched.
• Data Item Deleted: Triggered when an item is removed, or when a collection is truncated.

To handle an event, register a handler with the event's method, such as items.onDataItemCreated(), in a Backend Events extension.

The event object

Each handler receives an event object with these properties:

• entity: The item that changed, including its _id and dataCollectionId. For Data Item Created and Data Item Updated, it also includes data, the item's field values.
• metadata: Details about the event, such as eventTime and the event's _id.

What data events can't do

Data events run after a change is already saved, so they work differently from validation or transformation logic:

• They can't validate or block a change. By the time Wix triggers the event, the change is already saved. To validate data, check it in your code before you call the Data API. Checks in frontend code can be bypassed, so validate in backend code, and set the collection's permissions so that visitors can't write to it directly. To prevent duplicate values in a field, add a unique index.
• They can't modify the item before it's saved. To change an item in response to an event, update it with the Data API in the handler. The update triggers a new Data Item Updated event. If a Data Item Updated handler updates the same item every time it runs, it loops forever. Update the item only when the change is still needed, for example when a field doesn't have the value you want yet.
• They don't change what the caller receives. The code that made the change gets its result before your handler runs.
• They can arrive more than once. Use the event's metadata._id to spot and ignore duplicate events. To handle updates to the same item in order, compare metadata.entityEventSequence.

See also

• Add a Backend Events Extension in Studio Two
• Event Extensions