Event Extensions

Wix emits platform events when things happen across the platform, like a contact being created, an order being paid for, or a booking being confirmed. An event extension is a backend extension that runs code when one of those events occurs. For development paths where Wix doesn't host the backend, the same events are delivered as webhooks to an HTTP endpoint you provide instead.

For example, you can register an event extension for the Booking Confirmed event. When a customer confirms a booking, Wix calls the extension's handler with the booking details. The extension can use those details to send a confirmation email, sync the booking to an external calendar, or trigger other downstream logic.

Available events

Wix exposes events across the platform, including events from Wix business solutions like Bookings, Stores, eCommerce, and CRM, site activity like form submissions, member sign-ups, and file uploads, and app lifecycle events like app installs and uninstalls.

Authentication and permissions

Receiving an event requires a permission scope, just like calling a method. Each event in the API reference lists the scopes that allow an app to subscribe to it.

An event handler runs with no caller identity. Wix calls the handler on its own when an event fires, so there's no Wix user, member, or visitor identity attached, and the SDK's default auth in this context is null. To call Wix APIs from the handler, you must use elevation.

What elevated calls can do is bounded:

• For app-owned event extensions, elevation runs the call as the Wix app, bounded by the app's permission scopes, declared in the app's manifest.
• For site-owned Velo event handlers, elevation grants site admin authority.

For app-owned event extensions, the inbound event from Wix is signed so the handler can verify it actually came from Wix. The Wix CLI handles this verification.

Event extensions across development paths

The development path determines how code reacts to platform events:

• Sites: Don't use event extensions. They consume events through Velo backend event handlers, which only fire on the published site. See About Backend Events in Extend Websites.
• Wix-managed headless projects:
  • Full Wix integration (Astro): Use event extensions. The Wix CLI handles signature verification and decoding, so you write your handler in an SDK event handler and Wix runs it when the event fires. Each event type can have at most 1 handler per project. See Add Event Extensions with the Wix CLI.
  • Other frameworks: Don't support event extensions directly. Follow the same approach as self-managed headless projects.
• Self-managed headless projects: Don't use event extensions. They consume events through webhooks instead, with the endpoint hosted on infrastructure you manage. See About Webhooks in Build Apps.
• Wix-managed apps: Use event extensions. The Wix CLI handles signature verification and decoding, so you write your handler in an SDK event handler and Wix runs it when the event fires. Each event type can have at most 1 handler per project. See Add Event Extensions with the Wix CLI.
• Self-managed apps: Don't use event extensions. They consume events through webhooks instead, with the endpoint hosted on infrastructure you manage. See About Webhooks in Build Apps.
• Blocks apps: Consume events through Velo, the same way sites do. See About Backend Events in Extend Websites.

See also

• Events