Built-in events

This page lists every event VitNode core, the Content Engine and the first-party plugins emit, with its name, its payload and exactly when it fires. Use it to find the event to listen to. To write your first listener, or to emit events of your own, start with Events; every listener below is registered the same way, with no import from the emitting plugin, because the event map is global.

Quick startCopy Anchor Link

Pick a name from the tables below, write a listener for it, and register the listener on a top-level module's events array. Slow work, such as sending an email, goes to a queue task your plugin registers:

import { buildQueueTask } from '@vitnode/core/api/lib/queue'
import { z } from 'zod'

const zodPayload = z.object({ userId: z.number().int().positive() })

export const welcomeMemberTask = buildQueueTask({
  name: 'welcome-member',
  handler: async (c, payload) => {
    const { userId } = zodPayload.parse(payload)

    await c.get('log').debug(`Welcoming member #${userId}`)
  },
})

import { buildEventListener } from '@vitnode/core/api/lib/events'

import { manifest } from '@/manifest.gen'

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

export const notesModule = buildModule({
  name: 'notes',
  routes: [listNotesRoute, showNoteRoute],
  queueTasks: [welcomeMemberTask], 
  events: [welcomeListener], 
})

The payload type comes from the event name, and the delivery rules are the same for a core event as for one of your own.

Listener contextCopy Anchor Link

A listener runs inside the request that emitted the event and receives that request's c. For user.created, that is core's sign-up request, so:

Content Engine events emitted by core's scheduled-publishing task show the split most clearly. c.get('plugin') is @vitnode/core there too, while the envelope's pluginId names the content type's owner (see The envelope's owner).

Core events (@vitnode/core)Copy Anchor Link

Nineteen names, all declared in VitNodeEvents in packages/vitnode/src/api/models/events.ts. Every one except user.deleted, which core never emits, fires after the write it describes has committed.

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))
  },
})

Notification eventsCopy Anchor Link

Eight names, declared in VitNodeEvents in packages/vitnode/src/api/models/events.ts. Seven of them fire after an administrator's change in AdminCP → Notifications has been saved, and the envelope's actor is that administrator. notifications.preferences_updated is about one member: it fires when their own preferences are saved, by them or by staff on their AdminCP user page.

A listener would post an audit entry to your staff channel when someone pauses, deletes or resets everything, or note when staff changed how a single member is notified.

Moderation eventsCopy Anchor Link

Eleven names, declared in VitNodeEvents in packages/vitnode/src/api/models/events.ts and emitted by core with pluginId: "@vitnode/core". Each fires after its database write commits. The envelope's actor is the reporter for created, the administrator for report_reason.* and the moderator for the rest. Adding an internal note emits nothing. See Moderation.

A hide or restore from the ModCP also emits the content type's own content.{id}.hidden or unhidden event, because it goes through the same visibility service as the AdminCP.

A listener would notify a staff channel when a report arrives, or keep a per-moderator count of resolved reports.

AI eventsCopy Anchor Link

Declared in VitNodeEvents in packages/vitnode/src/api/models/events.ts. The two ai.run.* events are emitted by the shared AI runner (see AI errors and limits). They fire after the run was settled, so its cost and points are already in the history when a listener reads it. A failing listener never breaks the run - or the ALT write.

userId is null for system work such as automatic ALT text. Prompts and outputs are never part of the payload.

files.alt.updated fires after the core_files_alt rows were written. languageCodes lists only the languages that actually changed, and origin is "ai" for the background job or "human" for PUT /admin/files/{id}/alt. Removing a language's ALT text emits nothing.

A listener would post a notice when an editor's AI suggestion fails, count AI usage per plugin in your own analytics, or purge cached pages that render an image whose ALT text just changed.

Payment eventsCopy Anchor Link

Declared in VitNodeEvents in packages/vitnode/src/api/models/events.ts and emitted by payments after the new status is committed, once per status change, whichever path found it: the webhook route, a customer's status refresh or the reconcile-payments cron job. Every event has the same payload.

amount is in minor units, pluginId is the plugin that created the payment and reference is that plugin's own id, so filter on pluginId first. A checkout the provider refused to create also emits payment.failed; the stored payment then has an errorCode such as amount_too_small.

With the default local adapter a listener runs inside the request that changed the status, and a failing listener is logged, not retried. Derive what a member owns from the stored payment (c.get("payments").listByReference()), and use these events for side effects such as a thank-you notification.

A listener would send a receipt notification, post to a sales channel, or clear a cached page that shows the buyer's purchases.

Page layout eventsCopy Anchor Link

One name, declared in VitNodeEvents in packages/vitnode/src/api/models/events.ts. It fires after the layout row has been written, and not at all when a save changed nothing.

export const pageLayoutAuditListener = buildEventListener({
  event: 'core.page-layout.updated',
  name: 'audit-page-layout',
  handler: async (c, payload, envelope) => {
    await c
      .get('log')
      .debug(
        `${envelope.actor.type} #${envelope.actor.id ?? '-'} changed ${payload.changedZones.join(', ')} on ${payload.pageId}`,
      )
  },
})

Content Engine eventsCopy Anchor Link

Every content type declared with the Content Engine gets its own event names, built from its id: content.<id>.<action>. This section is the field-by-field reference; Content Engine events has the short action table and a subscribe walkthrough. For the newsroom plugin's newsroom.story that means content.newsroom.story.created, and for the blog's blog.post it means content.blog.post.created.

Every payload's contentId (and sourceId and duplicatedFromId) has the content type's id type: a number for the default serial strategy, a string for uuid and bigint. A bigint id arrives as its exact decimal string, so never pass it through Number().

Which actions exist depends on what the definition opts into. A content type that declares nothing beyond its fields emits three events; one that declares everything emits nineteen.

The gating is in the types, not just at runtime: ContentEventsFor expands to literal keys only for the features the definition enables. The newsroom plugin's newsroom.story declares editorial, so content.newsroom.story.restored type-checks; newsroom.category is a name and a slug and nothing else, so content.newsroom.category.restored is not a key on the map and a listener for it does not compile.

Record eventsCopy Anchor Link

Translation eventsCopy Anchor Link

A content type with localization emits one event per translation mutation, in addition to the record events above. Every one of them carries locale and languageId, so a listener never has to go and ask which language moved.

Delivery eventsCopy Anchor Link

A content type with delivery emits two more when its public URL moves. Both arrive alongside the lifecycle event that moved it - updated, restored, a publication transition or a translation_* - never instead of one: a field moving and a URL moving are different facts with different audiences.

A scheduled event may arrive twiceCopy Anchor Link

Announcements for a scheduled transition run in a durable queue task that retries whenever the event, the search write or a cache origin failed - and a retry re-emits an event some listeners already received. Delivery is at-least-once, deliberately: the alternative is a transactional outbox, which the engine does not have.

A listener whose work must happen exactly once keys off scheduleId, which is stable across every attempt at the same booking:

handler: async (c, payload) => {
  if (payload.scheduleId && (await alreadyDone(payload.scheduleId))) return

  await sendTheAnnouncement(payload.contentId)
}

An interactive publish is emitted once, by the route that performed it, and carries no scheduleId.

The other way out is an idempotency key on whatever the listener writes. A notification published with idempotencyKey: `post:${payload.contentId}` turns a second run into a no-op. See Idempotency keys.

The envelope's owner is the content type's pluginCopy Anchor Link

pluginId on the envelope answers "whose event is this", not "who was running at the time". Those come apart the moment something happens on a schedule: core owns the queue handler, so c.get('plugin') says @vitnode/core, while content.newsroom.story.published belongs to the newsroom plugin as much as it ever did.

queue task owner    @vitnode/core        ← who runs the handler
event envelope      newsroom             ← who owns the content type

The engine passes the owner explicitly on every emit, so ownership does not depend on which route module or queue handler invoked it. Your own code can do the same when it emits on someone else's behalf:

await c.get('events').emit('blog.post.created', payload, {
  pluginId: '@vitnode/blog', 
})

Omit the option and nothing changes: the envelope falls back to c.get('plugin') and then to @vitnode/core.

Failures are reported, not thrownCopy Anchor Link

emit() reports rather than throws. Listeners run after the write it describes has committed, and a broken listener is not a reason to tell somebody their save failed - so a failure comes back in the result instead, and is written to core_logs twice over: once per listener by the transport (Event listener "plugin:module:listener" for "<event>" failed: ...), and once as a JSON summary behind the greppable [content-effects] prefix by whichever effects helper emitted it - the editorial, translation, delivery and scheduled paths. A plain created/updated/deleted on a content type without editorial goes straight to the transport, so it produces the first line only.

const result = await c.get('events').emit('blog.post.created', payload)

result.delivered // listeners that ran
result.failures // [{ pluginId, module, listener, error }]

Interactive routes ignore that result on purpose, because the mutation succeeded either way. Background work usually should not: the scheduled-effects task inspects failures and retries the whole delivery when it is non-empty.

Content container eventsCopy Anchor Link

Four names, declared in VitNodeEvents in packages/vitnode/src/api/models/events.ts and shared by every container collection. Each fires after the write's transaction has committed. A refused write, such as deleting a desk that still has letters, emits nothing, and so does an update that changes nothing.

export const deskDeletedListener = buildEventListener({
  event: 'content.container.deleted',
  name: 'announce-deleted-desk',
  handler: async (c, payload) => {
    if (payload.definitionId !== 'newsroom.desks') return

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

Content access eventsCopy Anchor Link

import { buildEventListener } from '@vitnode/core/api/lib/events'

export const logForumAccess = buildEventListener({
  event: 'content.access.updated',
  name: 'log-forum-access',
  handler: async (c, payload) => {
    if (payload.family !== 'forum.forums') return

    await c
      .get('log')
      .info(`Forum ${payload.scopeId}: ${payload.changedActions.join(', ')}`)
  },
})

Content approval eventsCopy Anchor Link

Three names, declared in VitNodeEvents in packages/vitnode/src/api/models/events.ts and shared by every content type that waits for approval under a container's publishing policy. Each fires after its transaction commits. A refused decision, such as a 409 stale, emits nothing.

The record's own events are never duplicated. A pending create emits the content type's created when it is stored, and its published only when it is approved. Approving an edit emits one updated, with the changed fields. Rejecting emits nothing from the content type, because nothing on the record changed.

export const approvalRejectedListener = buildEventListener({
  event: 'content.approval.rejected',
  name: 'log-rejected-submission',
  handler: async (c, payload) => {
    if (payload.authorId === null) return

    await c.get('log').debug(
      `Submission ${payload.submissionId} by user ${payload.authorId} was rejected`,
    )
  },
})

Blog events (@vitnode/blog)Copy Anchor Link

blog.post.created and blog.post.updatedCopy Anchor Link

The adapter reads the article's categories back to fill in categoryId, so a record deleted in between is simply not announced - and so is one with no categories yet.

A listener would push a realtime "new post" notification, ping a webhook (from a queue task) that shares the post to social media, invalidate an external cache, or keep plugin-owned derived data such as related posts in sync.

blog.post.deletedCopy Anchor Link

No categoryId, unlike created and updated: the row is gone by the time this is emitted, so there is nothing left to read it from - and inventing one would put a wrong id into an audit trail. A listener that needs the category should watch content.blog.post.deleted and keep its own index.

A listener would remove the post from an external index or feed.

blog.category.created and blog.category.updatedCopy Anchor Link

A listener would keep a navigation menu or an externally-cached category tree in sync, or notify an external CMS of a taxonomy change.

blog.category.deletedCopy Anchor Link

A listener would drop the category from a cached navigation tree. It never has to fan out to the category's posts, because a category with posts cannot be deleted in the first place.

GotchasCopy Anchor Link

Deliberately not emitted yetCopy Anchor Link

High-frequency or consumer-less events are added only when a listener needs them, so the catalog stays meaningful. There is currently no user.signedIn, user.passwordResetRequested, or file.uploaded. If you need one, open an issue or PR - adding an event is a one-line emit plus an entry in the VitNodeEvents map. (user.deleted is the special case: it is already on the map, and waits on core growing a user-deletion flow.)

Live editing is quiet on the bus too. Taking or giving back a field lock, autosaving the shared draft and every keystroke in a co-edited rich text field happen many times a minute and change nothing anyone outside the form relies on, so none of them is an event. What does reach the bus is the commit: when someone presses Save, the record emits its usual updated (and its translations theirs), exactly as it would without live editing.

RelatedCopy Anchor Link