> ## Documentation Index
> Fetch the complete documentation index at: https://docs.malbox.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Event hooks

> How plugins respond to system events through hooks

Malbox's plugin system is event-driven. Rather than polling for changes or running on fixed schedules, plugins subscribe to specific events and respond when those events occur. This approach enables efficient, reactive analysis workflows where plugins only activate when relevant activity happens.

## How event hooks work

When you register a plugin with Malbox, you declare which events your plugin should respond to. The system uses two types of event channels:

* **Per-plugin channels** - each plugin publishes events on its own channel (`malbox/events/plugin/{id}`). Other plugins can subscribe to these to react to lifecycle and result events.
* **Daemon broadcast channel** - a shared channel (`malbox/events/daemon`) that delivers system-wide events (like `DaemonShutdown` and `ConfigReloaded`) to all plugins simultaneously.

The runtime uses a WaitSet-based reactor pattern. Your plugin sleeps until an event arrives, then routes it to the matching `#[malbox::on_event(...)]` handler, or to a catch-all `on_event` method if no specific handler exists.

## Event categories

Events are grouped into four categories based on what triggers them:

| Category          | Description                                                              |
| ----------------- | ------------------------------------------------------------------------ |
| **Task events**   | Fired during task lifecycle stages                                       |
| **Plugin events** | Fired when plugin processes start, stop, or produce results              |
| **Sample events** | Fired when samples are received or finish processing                     |
| **System events** | Fired for system-wide occurrences like shutdown or configuration changes |

## Subscribing to events

Plugins declare subscriptions in the `[events]` section of their `plugin.toml`. The subscription model is declarative - you specify which plugins to subscribe to, and the SDK runtime handles the IPC channel setup and routing.

```toml theme={null}
[events]
subscribe = ["string-extractor", "network-analyzer"]

[events.filters.PluginResultAvailable]
from_plugins = ["string-extractor"]
```

In your plugin code, use `#[malbox::on_event(...)]` handlers inside `#[malbox::handlers]` to react to specific event variants:

```rust theme={null}
#[malbox::handlers]
impl MyPlugin {
    #[malbox::on_event(PluginResultAvailable)]
    fn on_upstream_result(&self) -> Result<()> {
        info!("An upstream plugin produced a result");
        Ok(())
    }
}
```

## Plugin result chaining

Beyond reacting to lifecycle events, plugins can subscribe to other plugins' event channels. When a subscribed plugin produces a result, a `PluginResultAvailable` event fires with the source plugin name and result name. Your plugin's `on_event` handler receives this event, enabling reactive analysis pipelines where plugins chain off each other's output.

<Note>
  Events are lightweight signals - they carry minimal metadata (source plugin name and result name). Handle `PluginResultAvailable` events in your `on_event` handler to build analysis pipelines. Event hooks are only available to host plugins - guest plugins do not support event subscriptions.
</Note>

## Reference

For the complete list of available events and their parameters, see the [events reference](/reference/plugin-sdk/events).