Events

Each content type emits events named content.<id>.<action> after a change, such as content.newsroom.story.published. Subscribe to them to send a newsletter, sync an external index or purge a CDN, without touching the code that made the change.

Events come from the generated routes, scheduled publishing and contentEditorialEffects. The plain service(c) emits nothing. A save that changes nothing emits nothing either.

Event referenceCopy Anchor Link

Which events exist depends on what the definition enables. newsroom.category declares only fields and emits three. newsroom.story has publication, editorial with scheduling and delivery, and emits ten.

A few payload details that change what a listener does:

• contentId has the type of the content type's id strategy: a number for serial, a string for uuid and bigint. A bigint id arrives as its exact decimal string.
• A duplicate emits the copy's created with duplicatedFromId, one translation_created per copied language, then duplicated. duplicatedFromId is absent on an ordinary create.
• hidden and unhidden never replace published or unpublished, because hiding does not change the status.
• changedFields lists only the fields whose value actually moved, typed as the content type's own field names. On translation events it names localized fields only.
• restored replaces updated for a rollback, so a listener that cares about field changes should handle both.
• publishedAt is when the record first went live. It is never rewritten, and it can be missing, so guard for undefined.
• scheduledBy and scheduleId are set only when a schedule fired the change. actorUserId on scheduled is the same person as scheduledBy later.
• The delivery events arrive alongside updated, restored or a publication event, never instead of them. locale is null for a shared slug.

Container collections emit their own four events, content.container.created, updated, moved and deleted, listed in Container hierarchy.

A record waiting for approval emits its published or updated only when a moderator approves it, once. The submission itself emits content.approval.submitted, approved and rejected, listed in Built-in events.

The listener also receives an envelope with the actor, the time and pluginId. pluginId is always the plugin that owns the content type, even when a core queue task ran the change. Field-by-field descriptions are in Built-in events.

Subscribe to an eventCopy Anchor Link

import type { ContentEventsFor } from "@vitnode/core/content";

import type { categoryContentType } from "@/content/category";
import type { storyContentType } from "@/content/story";

declare module "@vitnode/core/api/models/events" {
  interface VitNodeEvents
    extends
      ContentEventsFor<typeof storyContentType>,
      ContentEventsFor<typeof categoryContentType> {}
}

import { buildEventListener } from "@vitnode/core/api/lib/events";
import { contentEventName } from "@vitnode/core/content";

import { storyContentType } from "@/content/story";

export const announceStoryListener = buildEventListener({
  event: contentEventName(storyContentType.id, "published"),
  name: "announce-published-story",
  description: "Logs every story that goes live",
  handler: async (c, payload) => {
    await c.get("log").debug(`Story ${payload.contentId} was published`);
  },
});

export const adminModule = buildModule({
  name: "admin",
  routes: [],
  modules: [
    buildContentAdminModule({
      containers: [deskContainers],
      contentTypes: [
        articleContent,
        categoryContent,
        commentContent,
        storyContent,
        explainerContent,
        bulletinContent,
        tagContent,
        eventContent,
        pageContent,
        letterContent,
      ],
    }),
  ],
  events: [announceStoryListener], 
});

Check the resultCopy Anchor Link

Save the file, publish a story in AdminCP → Newsroom → Stories and look for the debug line in the API terminal. A failing listener does not undo the change. The write has already committed, and the engine logs the failure.

Events from a scheduled publish run in a queue task that retries on failure, so the same published event can arrive twice. Make work that must happen once idempotent, for example keyed on scheduleId. See A scheduled event may arrive twice.