API Events

The API fires events before and after every write operation, and uses events to let plugins extend the Admin2 UI (sidebars, menubars, widgets, context panels, settings panels, custom field components, custom reports). Plugins react to these events to validate, modify data, cancel operations, or compose UI.

Page Events

Media Events

Config Events

Auth & User Events

GPM Events

Blueprint Events

Admin2 Integration Events

These are called while Admin2 composes the UI. Plugins append items/widgets/panels to the event data to register their integrations. The current user is passed in so listeners can gate registration on permissions.

Webhook Event Mapping

The outgoing webhook dispatcher listens for a subset of the above events and translates them into webhook events with the following names:

See the Webhooks endpoints for creating and managing webhook subscriptions. Webhooks fire after the API event, so listeners that mutate state via onApi* events will see their changes reflected in the outgoing payload.

Admin-Compatible Events (onAdmin*)

The API also fires the same events that Grav's classic Admin plugin fires. This ensures third-party plugins that subscribe to admin events (SEO Magic, Auto Date, Mega Frontmatter, etc.) work correctly regardless of whether changes come from the classic admin UI or the API/Admin2.

Both event families fire for every operation — admin events first, then API events.

Event Ordering Example

For a page create operation, events fire in this order:

1. onApiBeforePageCreate — API before event
2. onAdminCreatePageFrontmatter — admin frontmatter injection
3. onAdminSave — admin pre-save (plugins can modify the page)
4. onAdminAfterSave — admin post-save (indexing, notifications)
5. onApiPageCreated — API after event (triggers webhooks)

Route Registration

Plugins extend the API with custom endpoints by subscribing to one event:

See the Plugin API Integration guide for details.

Using Events in Your Plugin

public static function getSubscribedEvents(): array
{
    return [
        'onApiPageCreated' => ['onPageChanged', 0],
        'onApiPageUpdated' => ['onPageChanged', 0],
        'onApiPageDeleted' => ['onPageChanged', 0],
    ];
}

public function onPageChanged(Event $event): void
{
    // Rebuild search index, clear CDN cache, etc.
    $page = $event['page'] ?? null;
    $route = $event['route'] ?? $page?->route();

    $this->rebuildIndex($route);
}