Events
Every event a Content Engine content type emits, its payload and the feature that enables it, and how to subscribe with a typed event listener.
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 reference
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.
| Action | Payload | Needs |
|---|---|---|
created | { contentId, duplicatedFromId? } | always |
updated | { contentId, changedFields } | always |
deleted | { contentId } | always |
published | { contentId, publishedAt, scheduledBy?, scheduleId? } | publication |
unpublished | { contentId, scheduledBy?, scheduleId? } | publication |
restored | { contentId, changedFields, version, revisionId, restoredFromRevisionId } | editorial |
scheduled | { contentId, action, actorUserId, scheduledFor, scheduleId } | editorial.scheduling |
schedule_cancelled | { contentId, action, actorUserId, scheduleId } | editorial.scheduling |
translation_created | { contentId, locale, languageId, version, revisionId? } | localization |
translation_updated | { contentId, locale, languageId, version, changedFields, revisionId? } | localization |
translation_deleted | { contentId, locale, languageId, version, revisionId? } | localization |
translation_published | { contentId, locale, languageId, version, publishedAt, revisionId? } | localization + publication |
translation_unpublished | { contentId, locale, languageId, version, revisionId? } | localization + publication |
translation_restored | { contentId, locale, languageId, version, changedFields, revisionId, restoredFromRevisionId } | localization + editorial |
delivery_slug_changed | { contentId, slug, previousSlug, previousPath, canonicalPath, locale } | delivery |
delivery_redirect_created | { contentId, previousSlug, previousPath, canonicalPath, locale } | delivery |
duplicated | { actorUserId, contentId, contentTypeId, sourceId } | duplication |
hidden | { actorUserId, contentId, hiddenAt } | visibility |
unhidden | { actorUserId, contentId } | visibility |
A few payload details that change what a listener does:
contentIdhas the type of the content type's id strategy: anumberforserial, astringforuuidandbigint. A bigint id arrives as its exact decimal string.- A duplicate emits the copy's
createdwithduplicatedFromId, onetranslation_createdper copied language, thenduplicated.duplicatedFromIdis absent on an ordinary create. hiddenandunhiddennever replacepublishedorunpublished, because hiding does not change the status.changedFieldslists only the fields whose value actually moved, typed as the content type's own field names. On translation events it names localized fields only.restoredreplacesupdatedfor a rollback, so a listener that cares about field changes should handle both.publishedAtis when the record first went live, and it is never rewritten. Like every date in these payloads (scheduledFor,hiddenAt), listeners get aDate; code that emits one withemitContentEventpasses aDateand the engine sends it as an ISO string.emitContentEventruns after the write has committed, so a payload that does not match the content type's event schema is not thrown: no listener runs, the problem is logged, and the result'sfailuresholds one entry withmodule: "validation".scheduledByandscheduleIdare set only when a schedule fired the change.actorUserIdonscheduledis the same person asscheduledBylater.- The delivery events arrive alongside
updated,restoredor a publication event, never instead of them.localeisnullfor 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 event
Write the listener
contentEvent(contentType, action) from @vitnode/core/content returns the event's definition. The payload is typed from the content type, and an action the definition does not enable, such as contentEvent(categoryContentType, "published"), does not compile. Nothing needs registering: buildApiPlugin registers the definitions of every content type it registers.
import { buildEventListener } from "@vitnode/api/lib/events";
import { contentEvent } from "@vitnode/core/content";
import { storyContentType } from "@/content/story";
export const announceStoryListener = buildEventListener({
event: contentEvent(storyContentType, "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`);
},
});Add it to a top-level module
VitNode collects listeners only from the events array of a module passed directly to buildApiPlugin. A listener on a nested module never runs: buildApiPlugin throws in development to say so, and vitnode doctor reports it. Production ignores it.
export const adminModule = buildModule({
name: "admin",
routes: [],
modules: [
buildContentAdminModule({
containers: [deskContainers],
contentTypes: [
articleContent,
categoryContent,
commentContent,
storyContent,
explainerContent,
bulletinContent,
tagContent,
eventContent,
pageContent,
letterContent,
],
}),
],
events: [announceStoryListener],
});The blog plugin does the same with its blogLegacyEventListeners, which turn content.blog.post.created into the older blog.post.created event, and the forum listens to contentEvent(topicContentType, ...) to expire its cached stats.
Check the result
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.