Hooks

Actions, gates, and filters

const unsubscribe = ctx.hooks.action(
  "content.published",
  async (event, hookContext) => {
    await updateSearchIndex(event.contentId);
  },
  { priority: 100, id: "acme.search.index" }
);

// Optional manual cleanup. The host also cleans up on deactivate.
unsubscribe();

Ordering and cleanup

Lower priorities run first; the default is 100. Handlers at the same priority keep registration order. Set once: true for one dispatch. Registration returns an unsubscribe function, and the runtime automatically removes a plugin’s handlers when it deactivates.

Network-wide handlers

On a multisite installation a handler normally runs only on the sites that activated the plugin. Register it with network: true to run it on every site while the plugin is active on the main site, also on sites that never activated it. That needs the sensitive platform:network permission; without it, registering throws. Routes, jobs, and unmarked handlers stay per site. Inside the handler, ctx.settings and ctx.data still belong to the request’s site, so read the main site’s choices through ctx.network.mainSiteSettings.

ctx.hooks.filter("admin.body", async (html) => {
  const tag = await ctx.network?.mainSiteSettings.get<string>("adminTag");
  if (!tag || !/^[A-Z0-9-]+$/.test(tag)) return html;
  return `${html}<script src="/ext/acme.tags/tag.js" data-tag="${tag}"></script>`;
}, { network: true });

Hook context

The second handler argument carries correlation and identity—not secrets or server internals.

interface HookContext {
  siteId?: string;
  requestId?: string;
  source?: "http" | "job" | "cli" | "system";
  actor?: { userId?: string; role?: string };
}

Actions

Gates

ctx.hooks.gate("content.beforePublish", (event) => {
  if (!event.revision?.excerpt?.trim()) {
    event.cancel("Add an excerpt before publishing.");
  }
});

Filters

ctx.hooks.filter(
  "content.output",
  (content) => ({ ...content, enhancedBy: ctx.pluginId }),
  { priority: 120 }
);

Publish plugin-owned hooks

A plugin may emit actions, gates, and filters under its own manifest ID—for example acme.shop.order.created. Core namespaces cannot be spoofed. Export the payload types from your own package so integrators do not have to guess their shape.