Event Hooks: Reacting to Riven Lifecycle Events

Hooks are the primary way plugins react to things happening inside Riven. Each hook is a plain async function that receives a typed event payload, a DataSourceMap, a PluginSettings instance, and a logger — and optionally returns a response value that the Riven core acts on. Under the hood every hook gets its own dedicated BullMQ queue so it runs independently of other system work.

Anatomy of a hook handler

The handler signature is defined by createEventHandlerSchema in the SDK. Every handler receives the same four arguments regardless of event type:

type HookHandler<TEvent, TResponse = void> = (args: {
  event: Omit<TEvent, 'type'>; // the event payload, without the discriminant
  dataSources: DataSourceMap;  // access any DataSource registered by this plugin
  settings: PluginSettings;    // read plugin settings via settings.get(Schema)
  logger: Logger;              // Winston logger scoped to this job
}) => Promise<TResponse>;

Registering hooks in a plugin

Hooks live in the hooks object of your RivenPlugin export. Keys are event type strings; values are handler functions. All keys are optional — only subscribe to the events your plugin needs.

import type { RivenPlugin } from '@repo/util-plugin-sdk';

export const plugin: RivenPlugin = {
  name: pluginConfig.name,
  version: packageJson.version,
  dataSources: [TvdbAPI, TvMazeAPI],
  resolvers: [TvdbResolver, TvdbSettingsResolver],
  settingsSchema: TvdbSettings,

  hooks: {
    'riven.media-item.index.requested.show': indexTVDBMediaItem,
  },

  async validator({ dataSources }) {
    return dataSources.get(TvdbAPI).validate();
  },
};

BullMQ queue per hook

When Riven receives an event it fans it out to all registered plugin handlers. Each plugin’s handler runs inside its own queue named:

${eventType}.plugin[${pluginName}]

For example, the TVDB plugin’s indexing hook runs in the queue:

riven.media-item.index.requested.show.plugin[@repo/plugin-tvdb]

This means a slow or failing hook in one plugin never blocks another plugin’s hook for the same event.

Accessing DataSources inside hooks

Use dataSources.get(YourDataSourceClass) to retrieve an instance of any DataSource your plugin has registered. The DataSourceMap.get() method throws at runtime if the class is not found, catching mismatches early.

import { TvdbAPI } from '../datasource/tvdb.datasource.ts';
import { TvMazeAPI } from '../datasource/tvmaze.datasource.ts';

const myHook = async ({ dataSources, event }) => {
  const tvdb = dataSources.get(TvdbAPI);
  const tvMaze = dataSources.get(TvMazeAPI);
  // ...
};

Real-world example: TVDB indexing hook

The TVDB plugin hooks into riven.media-item.index.requested.show to populate show metadata. If the item has a tvdbId it fetches series and episode data from TVDB and timezone info from TVMaze, then returns a structured item payload for the Riven core to persist.

import { TvdbAPI } from '../datasource/tvdb.datasource.ts';
import { TvMazeAPI } from '../datasource/tvmaze.datasource.ts';
import { transformSeries } from '../transformers/transform-series.ts';

import type { MediaItemIndexRequestedShowEventHandler } from
  '@repo/util-plugin-sdk/schemas/events/media-item.index.requested.event';
import type z from 'zod';

export const indexTVDBMediaItem: z.infer<
  typeof MediaItemIndexRequestedShowEventHandler
> = async ({ dataSources, event }) => {
  if (event.item.tvdbId) {
    const api = dataSources.get(TvdbAPI);
    const tvMazeApi = dataSources.get(TvMazeAPI);

    const series = await api.getSeries(event.item.tvdbId);
    const episodes = await api.getAllEpisodesInOfficialOrder(event.item.tvdbId);
    const timezone = await tvMazeApi.getShowTimezone(event.item.tvdbId);

    return {
      item: transformSeries(event.item, series, episodes, timezone),
    };
  } else if (event.item.imdbId) {
    // IMDb-only path not yet implemented
    return null;
  }

  return null;
};

Use the exported handler type (e.g. z.infer<typeof MediaItemIndexRequestedShowEventHandler>) for the handler variable so TypeScript enforces the exact return shape the core expects.

All available hook events

Lifecycle

Event type	Fired when	Return type
`riven.core.started`	The Riven application has fully started	`void`
`riven.core.shutdown`	The application is shutting down gracefully	`void`

Content service

Event type	Fired when	Return type
`riven.content-service.requested`	The core polls for new media items to request	`{ movies, shows, updateIntervalSeconds }`

The riven.content-service.requested hook is how content-source plugins (e.g. a watchlist or Overseerr integration) push new media items into Riven. Return movies and shows arrays with at least one external ID each.

Item request

Event type	Fired when	Return type
`riven.item-request.create.success`	A new item request was created successfully	`void`
`riven.item-request.create.error`	An item request creation failed	`void`
`riven.item-request.create.error.conflict`	An item request failed due to a conflict (duplicate)	`void`
`riven.item-request.removed`	An item request was removed	`void`
`riven.item-request.update.success`	An item request was updated	`void`

Indexing

Event type	Fired when	Return type
`riven.media-item.index.requested.movie`	A movie needs metadata indexed	`{ item: IndexedMovieItem } \| null`
`riven.media-item.index.requested.show`	A show needs metadata indexed	`{ item: IndexedShowItem } \| null`
`riven.media-item.index.success`	A media item was indexed successfully	`void`
`riven.media-item.index.error`	Indexing failed	`void`
`riven.media-item.index.error.incorrect-state`	Indexing failed because the item was in an unexpected state	`void`

Return null from an index hook to indicate your plugin did not handle the item (e.g. because the required external ID is missing). The core collects results from all plugins and uses the first non-null response.

Scraping

Event type	Fired when	Return type
`riven.media-item.scrape.requested`	An indexed item needs torrent streams found	`{ id, results: Record<infoHash, title> }`
`riven.media-item.scrape.success`	Scraping completed successfully	`void`
`riven.media-item.scrape.error`	Scraping failed	`void`
`riven.media-item.scrape.error.incorrect-state`	Scraping failed because the item was in an unexpected state	`void`
`riven.media-item.scrape.error.no-streams-found`	Scraping completed but no streams were found	`void`

The results object maps torrent info hashes (SHA-1) to human-readable titles. Return an empty results map when no streams are found.

Downloading

Event type	Fired when	Return type
`riven.media-item.download.requested`	A torrent needs to be sent to a debrid service	`{ success, data: { torrentId, files } } \| { success: false, statusCode }`
`riven.media-item.download.cache-check-requested`	The core checks if a torrent is already cached	varies
`riven.media-item.download.provider-list-requested`	A list of available download providers is needed	varies
`riven.media-item.download.success`	Download completed	`void`
`riven.media-item.download.partial-success`	Download partially completed	`void`
`riven.media-item.download.error`	Download failed	`void`
`riven.media-item.download.error.incorrect-state`	Download failed because the item was in an unexpected state	`void`

Streaming

Event type	Fired when	Return type
`riven.media-item.stream-link.requested`	A playable URL is needed for a media entry	`{ success: true, data: { link, isPermalink, expiresAt? } } \| { success: false, statusCode }`
`riven.media-item.stream-link.health-check.requested`	The core checks if an existing stream link is still valid	varies

Subtitles

Event type	Fired when	Return type
`riven.media-item.subtitle.requested`	Subtitles are needed for a media item	varies

Hook typing with the SDK event schemas

Each event has a corresponding handler schema exported from the events index. Using these schemas for type inference means TypeScript catches mismatches in the return type:

import type { ContentServiceRequestedEventHandler } from
  '@repo/util-plugin-sdk/schemas/events/content-service-requested.event';
import type z from 'zod';

export const fetchWatchlist: z.infer<
  typeof ContentServiceRequestedEventHandler
> = async ({ dataSources, settings }) => {
  const api = dataSources.get(WatchlistAPI);
  const { updateIntervalSeconds } = settings.get(WatchlistSettings);
  const items = await api.getWatchlist();

  return {
    movies: items.filter((i) => i.type === 'movie').map(toExternalIds),
    shows: items.filter((i) => i.type === 'show').map(toExternalIds),
    updateIntervalSeconds,
  };
};

Why does the event payload omit the `type` field?

The type discriminant is used internally by Riven to route the event to the correct queue and handlers. By the time your hook function is called, routing is already done, so the type field is stripped from the payload to keep handler signatures clean. You already know the event type from the key you subscribed to.

Overview

Building a Plugin

Reference

Event Hooks: Reacting to Riven Lifecycle Events

Anatomy of a hook handler

Registering hooks in a plugin

BullMQ queue per hook

Accessing DataSources inside hooks

Real-world example: TVDB indexing hook

All available hook events

Lifecycle

Content service

Item request

Indexing

Scraping

Downloading

Streaming

Subtitles

Hook typing with the SDK event schemas

Build docs developers (and LLMs) love

Overview

Building a Plugin

Reference

Documentation Index

​Anatomy of a hook handler

​Registering hooks in a plugin

​BullMQ queue per hook

​Accessing DataSources inside hooks

​Real-world example: TVDB indexing hook

​All available hook events

​Lifecycle

​Content service

​Item request

​Indexing

​Scraping

​Downloading

​Streaming

​Subtitles

​Hook typing with the SDK event schemas

Build docs developers (and LLMs) love

Anatomy of a hook handler

Registering hooks in a plugin

BullMQ queue per hook

Accessing DataSources inside hooks

Real-world example: TVDB indexing hook

All available hook events

Lifecycle

Content service

Item request

Indexing

Scraping

Downloading

Streaming

Subtitles

Hook typing with the SDK event schemas