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)

Subscribing from a Plugin

Do not gate the subscription of these admin-compatible events behind an isAdmin() check in onPluginsInitialized(). When a save comes through the API (which is how Admin2 saves everything), the request is not handled by the classic Admin plugin, so $grav['admin'] is registered later during request dispatch by the API's AdminProxy. At onPluginsInitialized() time it is not yet set, so isAdmin() still returns false and any handlers you register inside an isAdmin() block are never subscribed. The result is a plugin whose save/delete logic silently never runs under Admin2.

!!! A common 1.7-era pattern was to register onAdminAfterSave only when isAdmin() was true. That no longer works for API/Admin2 writes. These events only fire during admin/API write operations anyway, so it is safe to subscribe to them unconditionally.

Register them directly in getSubscribedEvents(), or unconditionally in onPluginsInitialized():

public static function getSubscribedEvents(): array
{
    return [
        'onPluginsInitialized'    => ['onPluginsInitialized', 0],
        // Always registered — these only fire during admin/API writes:
        'onAdminAfterSave'        => ['onObjectSave', 0],
        'onAdminAfterDelete'      => ['onObjectDelete', 0],
        'onAdminAfterSaveAs'      => ['onObjectMove', 0],
        'onFlexObjectAfterSave'   => ['onObjectSave', 0],
        'onFlexObjectAfterDelete' => ['onObjectDelete', 0],
    ];
}

Note that Flex objects (and Flex Pages) fire onFlexObjectAfterSave / onFlexObjectAfterDelete — the *After* variants — not the bare onFlexObjectSave / onFlexObjectDelete names. Subscribe to the variant that matches the data you need.

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);
}