Events

Backend events let your code react when something happens on a Wix site, app, or account. Instead of polling for changes or checking state on every request, you register a handler once, and Wix runs it when the matching event occurs.

Events come from across the platform:

• Wix business solutions: Wix's built-in business apps, such as Stores, Bookings, eCommerce, and CRM. They emit events as their data changes.
• Site-level activity: Interactions on a published site, driven by its visitors and members.
• Platform-level activity: Platform-wide actions that aren't tied to a single business solution, such as app and file management.
• Account-level activity: Operations that span an entire Wix account rather than a single site. Available to Enterprise and Wix Channels partners.

For example, an event is triggered when:

• An order is paid (business solution)
• A booking is canceled (business solution)
• A contact is created or updated (business solution)
• A file is uploaded to the Media Manager (platform-level)
• An app is installed on or removed from a site (platform-level)
• A form is submitted (site-level)
• A member signs up (site-level)
• A CMS collection item changes (site-level)
• A new site is created (account-level)

Event types and payloads

The API Reference catalogs all available events, each listed alongside the API methods that trigger it.

Every event has an event type identifying the kind of event, such as wix.contacts.v4.contact_created, and a payload describing what happened. The payload carries the affected entity's data and metadata about the event, including which identity triggered it: a visitor, member, Wix user, or app.

The platform delivers each event to whichever handler is registered for it on the affected site, app, or headless project.

Handler identity

The payload records who or what triggered the event, but that's data about the event, not the identity your code runs as. The handler itself runs with no caller identity: Wix invokes it automatically when the event occurs, so there's no logged-in Wix user, member, or visitor in context. As a result, methods that depend on a caller identity, such as the Get Current Member method, won't work inside a handler. To call Wix APIs that require permissions, use elevation.

Event delivery

Event delivery is asynchronous and at least once.

On any development path, an event can occasionally be delivered more than once or out of order, so write handlers to be idempotent. Reprocessing the same event shouldn't change the outcome. A common approach is to record processed event IDs and skip any you've already handled.

Delivered payloads always reflect the state at the time of the event, even when redelivered.

Events and webhooks

An event is the thing that happens. How it reaches your code depends on your development path, and it takes one of two forms:

• An event handler. You write a handler, such as onOrderPaid, that Wix calls when the event occurs. Your code never touches the HTTP layer. The SDK and Velo deliver events this way.
• A webhook. When Wix delivers an event to a server you host, it sends an HTTP POST whose body is a signed JSON Web Token (JWT). Registering a callback URL to receive these HTTP requests is the webhook pattern.

Both forms carry the same events. Wix-managed paths verify and decode the JWT for you and hand your code a plain event object. Self-managed paths receive the raw JWT and must verify it themselves.

Account-level webhooks

Enterprise and Wix Channels partners can also subscribe to account-level webhooks, which cover operations that span an entire Wix account, such as site creation, folder management, and team member changes. They're delivered only as webhooks, to a server you host, as a signed JWT, with no SDK or Velo handler form. If your account is a parent account, events from its child accounts propagate to the same callback URL.

Events across development paths

The development path determines how events reach your code:

• Sites: Consume events through Velo backend event handlers, which are only triggered on the published site, not in preview. The SDK's event handlers can't be used directly on sites. For implementation, see Define Backend Event Handlers in Extend Websites.
• Wix-managed headless projects: Consume events through event extensions. The Wix CLI handles signature verification and decoding for you, so all you need to do is code your response to the event in an SDK event handler. For implementation, see Add Event Extensions with the Wix CLI.
• Self-managed headless projects: Consume events through webhooks, since Wix doesn't host their backend. You host the callback URL that receives the webhook and verify the signed JWT yourself. For implementation, see Handle Webhook Events with the JavaScript SDK in Build Apps.
• Wix-managed apps: Consume events through event extensions. The Wix CLI handles signature verification and decoding for you, so all you need to do is code your response to the event in an SDK event handler. For implementation, see Add Event Extensions with the Wix CLI.
• Self-managed apps: Consume events through webhooks, since Wix doesn't host their backend. You host the callback URL that receives the webhook and verify the signed JWT yourself. For implementation, see Handle Webhook Events with the JavaScript SDK in Build Apps.
• Blocks apps: Consume events the same way sites do. For implementation, see Define Backend Event Handlers in Extend Websites.