Built-in Events

Emitted from UserModel.signUp, which is the one insert path into core_users - so it covers the public sign-up form, user creation in the AdminCP, and the first sign-in through an SSO provider.

A listener would send a welcome or verification email (via a queue task so it retries), subscribe the address to a newsletter audience, or provision plugin-owned data such as a profile row.

export const welcomeListener = buildEventListener({
  event: 'user.created',
  name: 'send-welcome-email',
  handler: async (c, payload) => {
    await c.get('queue').dispatch({
      name: 'send-welcome-email',
      payload: { userId: payload.userId, email: payload.email },
    })
  },
})

Emitted by the AdminCP user PATCH after it commits - profile fields (email, name, name code) and/or role assignments - and when a member saves their own profile fields or time zone. The payload carries the user's current values.

A listener would sync the identity into an external system (CRM, mailing list), invalidate a plugin-owned cache keyed by user, or audit-log the staff edit using the envelope's actor.

Emitted after an avatar is stored and attached to the user, or after it is removed. The same event covers the profile page and the AdminCP - the envelope's actor tells the two apart.

A listener would push the new picture to a chat integration, regenerate a cached feed card, or audit-log a staff change with the envelope's actor.

The cover image's twin of user.avatar.updated, with the same payload and the same two triggers.

Emitted after the core_users_sso row is committed, from two places:

• SSOModel.link - a social identity that arrived with an already-registered email is tied to that account once its password checks out;
• SsoConnectionModel.callback - a signed-in member connects a provider from Connected accounts. The provider's email may differ from the account's; email is always the VitNode account's.

It does not fire on the first sign-in through a provider (that is a user.created) or on a later sign-in through an identity that is already linked.

A listener would notify the account owner that a new sign-in method was added, or audit-log the link with the envelope's actor.

Emitted by SsoConnectionModel.disconnect after the connection and its profile sync settings are deleted. Nothing is revoked at the provider - the member still has to remove the app there if they want to.

A listener would email the member that a sign-in method was removed.

Emitted when at least one profile field actually changed because of a provider. Fields that were missing, not allowed or already equal are left out, and an avatar that failed to download never counts. A name change also emits user.updated, and an avatar change emits user.avatar.updated.

A listener would refresh a search index or a cached member card.

Emitted once an unconfirmed address becomes confirmed: when a member clicks the link from their sign-up email, when they complete a password reset (the reset link went to the same mailbox), or when staff press Verify Email on the AdminCP user page. A reset on an account that was already confirmed emits nothing here. See Email Verification.

A listener would send a welcome email or unlock a "verified member" badge.

Emitted after a new password hash is stored - when a member completes a password reset, or when staff set one from the AdminCP user page. The staff route answers 403 while password sign-in is turned off, so this never fires for a password nobody could use. Both paths then sign the account out everywhere, so user.sessions.revoked follows right after.

A listener would email the account owner that their password changed, and use the envelope's actor to say whether they or an administrator did it.

Emitted by revokeSessions once a user's sessions are deleted and their cached copies dropped. It covers both session kinds - the site session and the AdminCP session - and fires from every place that signs somebody out remotely: a member ending one of their own devices, staff ending one device or all of them, and a password change.

A listener would write a security audit entry, or warn the member when staff signed them out.

Emitted by SsoConnectionModel.savePreferences after the profile-field sources and the per-provider sync switches are saved - from Settings → Connected accounts or from the AdminCP user page. It fires on every successful save, even when nothing changed.

A listener would audit-log who changed where an account's profile comes from.

The name and payload live on the VitNodeEvents map so listeners type-check, but core never emits it: there is no user-deletion flow yet. It is the agreed-upon name for plugins that implement account deletion themselves, and core will emit it once deletion lands.

Emitted after a role is created or edited in the AdminCP, including its translated names - those live in core_languages_words, so the payload has no name field to carry.

A listener would provision plugin-side permission defaults for a new role, or refresh an externally-cached permission matrix when one changes.

Emitted after the delete transaction commits. Its translated names are removed with it, and its secondary-role assignments and staff-permission entries are dropped by database cascade. Members point at their primary role through a NOT NULL restricted foreign key, so anyone in the role is reassigned before the delete - by the time this fires, no user references it.

A listener would clean up plugin-owned rows keyed by role id. The role row is already gone, so key the cleanup off payload.roleId rather than re-reading core_roles:

export const roleCleanupListener = buildEventListener({
  event: 'role.deleted',
  name: 'cleanup-role-settings',
  handler: async (c, payload) => {
    await c
      .get('db')
      .delete(shop_role_settings)
      .where(eq(shop_role_settings.roleId, payload.roleId))
  },
})

The item's translated title and description live in core_languages_words, so the payload carries only the id. On deleted the row is already gone; key any cleanup off payload.navigationId.

A listener would purge a CDN's cached HTML, or log who changed the menu and when.

Fires after a drag-and-drop in the AdminCP saved a menu. The payload is that entire menu as the administrator now sees it, one level deep - the header menu or the bottom bar, never both.

Emitted by PUT /pages/layout once the one core_page_layouts row for that page has been written. A page's layout is stored as overrides only, so changedZones names the zones whose override actually moved - not every zone the editor happened to send, and not the zones still sitting on the defaults their defineEditablePage declaration ships.

A save that changes nothing writes nothing and emits nothing, so a listener never fires for a no-op. Saving a zone back to its shipped default removes that override, which counts as a change and is reported here.

A listener would purge whatever the front end caches for that page. The layout is read by page id, so the id in the payload is the whole cache key:

export const pageLayoutCacheListener = buildEventListener({
  event: 'core.page-layout.updated',
  name: 'expire-page-cache',
  handler: async (c, payload) => {
    await c.get('cache')?.delete(`page:${payload.pageId}`)
  },
})

A listener would mirror the row into a plugin-owned projection, reindex it for an external search engine, or purge a CDN entry. changedFields is what lets it skip the work when the field it cares about did not move.

publishedAt is when the record went live for the first time and is never rewritten by a later unpublish and republish. scheduledBy and scheduleId are present only when a booking caused the transition; an interactive publish carries neither.

A listener would announce the record (a newsletter, a social post, a realtime toast), add or remove it from an external index, or expire a cache that only holds public rows. Because the same publish can arrive twice, key anything that must happen once off scheduleId - see A scheduled event may arrive twice.

A rollback to an earlier revision's field values. It carries changedFields exactly like updated, so porting an updated listener is a rename rather than a rewrite - which is why a restore emits one event and not both.

A listener would do exactly what its updated listener does. A restore never moves status, publishedAt or hiddenAt, so nothing watching visibility has to handle it.

Booking a transition changes no field value, so it consumes no version and writes no revision - scheduled is a different fact from published. When the booking fires, the transition emits the ordinary published or unpublished with scheduleId and scheduledBy set.

A listener would show an editorial calendar, warn an author that two bookings collide, or pre-warm a render shortly before scheduledFor.

A duplicate first emits the copy's ordinary created (with duplicatedFromId) and one translation_created per copied language, then duplicated. Indexing already ran for created, so duplicated is a notification only.

A listener would credit the original author in an audit log, or link the copy to its source in a plugin-owned table.

Hiding takes a record off the public site without touching status or publishedAt, so a hidden record emits neither unpublished nor, when unhidden, published. Hiding a record that is already hidden emits nothing.

A listener would purge a CDN entry, pull the record from an external search engine, or tell the author that a moderator took their article down. Hiding a draft emits the event too, though nothing public changed.

A listener would invalidate one locale's cache, reindex one language's search document, or tell a translation vendor that the Polish copy moved.

A shared update and a Polish translation update are different domain facts with different consequences: one invalidates every language, the other invalidates one. A listener that had to inspect changedFields to tell them apart would get it wrong the first time a field was renamed - so changedFields on a translation event names localized fields only, and never a shared one.

A listener would purge a CDN entry, write to an edge redirect table, or tell an external search engine the address changed. Without this event it would have to inspect changedFields for a slug field whose name it cannot know.

delivery_redirect_created fires only when the old address had genuinely been publicly addressable - the engine has a retired history row to prove it. An article whose slug was corrected three times while it was still a draft emits three delivery_slug_changed and not one redirect; a published article that moves emits one of each. That is the difference between "a URL now needs a redirect" and "somebody edited a field".

There is deliberately no sitemap event either: every mutation that changes a sitemap line already emits published, unpublished, deleted or one of these two, and a third carrying no new information would be one more thing to keep consistent for no listener's benefit.

Emitted by createContentContainerService, so the AdminCP routes and your own code that uses the service emit the same events. Siblings renumbered by a move or a delete do not get events of their own.

A listener would rebuild a navigation menu kept outside VitNode, or post to a staff channel when a board is deleted:

export const boardDeletedListener = buildEventListener({
  event: 'content.container.deleted',
  name: 'announce-deleted-board',
  handler: async (c, payload) => {
    if (payload.definitionId !== 'example.boards') return

    await c.get('log').warn(`Board ${payload.containerId} was deleted`)
  },
})