Events

Each content type emits events named content.<id>.<action> after a change, such as content.example.article.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. example.category declares only fields and emits three; example.article has publication, editorial with scheduling and delivery, and emits ten.

A few payload details that change what a listener does:

• 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.

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 { articleContentType } from "@/content/article";
import type { categoryContentType } from "@/content/category";

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

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

import { articleContentType } from "@/content/article";

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

export const adminModule = buildModule({
  pluginId: CONFIG_PLUGIN.pluginId,
  name: "admin",
  routes: [],
  modules: [
    buildContentAdminModule({
      pluginId: CONFIG_PLUGIN.pluginId,
      contentTypes: [articleContent],
    }),
  ],
  events: [announceArticleListener], 
});

Check the resultCopy Anchor Link

Restart pnpm dev, publish an article in AdminCP → Example → Articles 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.