webiny-event-handler-pattern

name: webiny-event-handler-pattern context: webiny-api description: > EventHandler implementation pattern — handle method, event payloads, filtering, DI, domain event definition, publishing events from UseCases, and reacting to external events. Use this skill to implement any Webiny EventHandler (before/after hooks) or to define and publish your own domain events.

EventHandler Pattern

What It Is

An EventHandler reacts to domain events in the Webiny lifecycle (e.g., EntryBeforeCreateEventHandler, TenantAfterDeleteEventHandler). Each handler is a DI abstraction with a single handle method.

Naming Convention

• {Entity}Before{Operation}EventHandler — fires before persistence, can validate/transform/reject
• {Entity}After{Operation}EventHandler — fires after persistence, for side effects

Interface Shape

interface SomeEventHandler.Interface {
    handle(event: SomeEventHandler.Event): Promise<void>;
}

The Event is a DomainEvent<Payload> where the payload contains the entity and input data.

Architecture Rule: Always Wrap Logic in a Reusable Abstraction (MANDATORY)

Never put business logic directly inside an EventHandler. EventHandlers are thin orchestrators — they receive an event and delegate to an injected service or use case. The real logic lives in a dedicated abstraction.

Why: Inline handler logic cannot be reused by other handlers, GraphQL resolvers, or CLI commands.

Always follow this structure:

features/
├── myService/             ← the reusable abstraction
│   ├── abstractions.ts
│   ├── feature.ts
│   └── MyService.ts
└── syncOnCreate/          ← thin handler that injects the service
    ├── feature.ts
    └── EntryAfterCreateHandler.ts

The EventHandler feature and the service feature are registered separately in Extension.ts.

How to Implement

import { SomeEventHandler } from "webiny/api/<category>";
import { MyService } from "../myService/abstractions.js";

// ✅ Handler is a thin orchestrator — no business logic here
class MyHandler implements SomeEventHandler.Interface {
  constructor(private myService: MyService.Interface) {}

  async handle(event: SomeEventHandler.Event) {
    const { entity, model } = event.payload;

    // For CMS handlers: ALWAYS filter by model
    if (model.modelId !== "myModel") return;

    await this.myService.doWork(entity);
  }
}

export default SomeEventHandler.createImplementation({
  implementation: MyHandler,
  dependencies: [MyService]
});

See webiny-api-architect for how to define MyService as a proper abstraction.

Injecting Dependencies

EventHandlers can depend on UseCases, platform services, or custom abstractions:

import { SomeEventHandler } from "webiny/api/<category>";
import { SomeUseCase } from "webiny/api/<category>";

class MyHandler implements SomeEventHandler.Interface {
  constructor(private someUseCase: SomeUseCase.Interface) {}

  async handle(event: SomeEventHandler.Event) {
    const result = await this.someUseCase.execute({
      /* ... */
    });
  }
}

export default SomeEventHandler.createImplementation({
  implementation: MyHandler,
  dependencies: [SomeUseCase]
});

Defining Your Own Domain Events

When your feature needs to notify other parts of the system about important domain actions, define your own events.

Event Payload Types (in abstractions.ts)

Event payloads and handler abstractions live in abstractions.ts. The events.ts file only contains the event classes.

// features/disableEntity/abstractions.ts
import { createAbstraction } from "@webiny/feature/api";
import type { IEventHandler } from "@webiny/api-core/features/EventPublisher";
import type { Entity } from "~/shared/Entity.js";
// Forward declaration — actual classes are in events.ts
import type { EntityBeforeDisableEvent, EntityAfterDisableEvent } from "./events.js";

// Event Payload Types
export interface EntityBeforeDisablePayload {
  entity: Entity;
}

export interface EntityAfterDisablePayload {
  entity: Entity;
}

// Handler Abstractions — one per event
export const EntityBeforeDisableEventHandler = createAbstraction<
  IEventHandler<EntityBeforeDisableEvent>
>("MyPackage/EntityBeforeDisableEventHandler");

export namespace EntityBeforeDisableEventHandler {
  export type Interface = IEventHandler<EntityBeforeDisableEvent>;
  export type Event = EntityBeforeDisableEvent;
}

export const EntityAfterDisableEventHandler = createAbstraction<
  IEventHandler<EntityAfterDisableEvent>
>("MyPackage/EntityAfterDisableEventHandler");

export namespace EntityAfterDisableEventHandler {
  export type Interface = IEventHandler<EntityAfterDisableEvent>;
  export type Event = EntityAfterDisableEvent;
}

Event Class Definition (events.ts)

Event classes import payload types and handler abstractions from abstractions.ts.

// features/disableEntity/events.ts
import { DomainEvent } from "@webiny/api-core/features/EventPublisher";
import { EntityBeforeDisableEventHandler, EntityAfterDisableEventHandler } from "./abstractions.js";
import type { EntityBeforeDisablePayload, EntityAfterDisablePayload } from "./abstractions.js";

export class EntityBeforeDisableEvent extends DomainEvent<EntityBeforeDisablePayload> {
  eventType = "entity.beforeDisable" as const;

  getHandlerAbstraction() {
    return EntityBeforeDisableEventHandler;
  }
}

export class EntityAfterDisableEvent extends DomainEvent<EntityAfterDisablePayload> {
  eventType = "entity.afterDisable" as const;

  getHandlerAbstraction() {
    return EntityAfterDisableEventHandler;
  }
}

Publishing Events from a UseCase

// features/disableEntity/DisableEntityUseCase.ts
import { EventPublisher } from "@webiny/api-core/features/EventPublisher";
import { EntityBeforeDisableEvent, EntityAfterDisableEvent } from "./events.js";

class DisableEntityUseCase implements UseCaseAbstraction.Interface {
  constructor(
    private eventPublisher: EventPublisher.Interface,
    private getEntityById: GetEntityByIdUseCase.Interface,
    private updateEntity: UpdateEntityUseCase.Interface
  ) {}

  async execute(entityId: string): Promise<Result<void, UseCaseAbstraction.Error>> {
    const getResult = await this.getEntityById.execute(entityId);
    if (getResult.isFail()) return Result.fail(getResult.error);

    const entity = getResult.value;

    // Publish BEFORE event (can be intercepted to reject)
    await this.eventPublisher.publish(new EntityBeforeDisableEvent({ entity }));

    // Perform the operation
    const updateResult = await this.updateEntity.execute(entityId, { status: "disabled" });
    if (updateResult.isFail()) return Result.fail(updateResult.error);

    // Publish AFTER event (for side effects)
    await this.eventPublisher.publish(new EntityAfterDisableEvent({ entity: updateResult.value }));

    return Result.ok();
  }
}

export default UseCaseAbstraction.createImplementation({
  implementation: DisableEntityUseCase,
  dependencies: [EventPublisher, GetEntityByIdUseCase, UpdateEntityUseCase]
});

Reacting to External Events

To react to events from other packages (e.g., CMS entry deletion), implement the external event's handler abstraction:

// features/cleanupOnEntryDelete/CleanupOnEntryDeleteHandler.ts
import { EntryAfterDeleteEventHandler } from "@webiny/api-headless-cms/features/contentEntry/DeleteEntry/events.js";
import { CleanupService } from "../cleanupService/abstractions.js";
import { MY_MODEL_ID } from "~/shared/constants.js";

class CleanupOnEntryDeleteHandler implements EntryAfterDeleteEventHandler.Interface {
  constructor(private cleanupService: CleanupService.Interface) {}

  async handle(event: EntryAfterDeleteEventHandler.Event): Promise<void> {
    const { entry, model } = event.payload;

    // ALWAYS filter by model — handler fires for ALL models
    if (model.modelId !== MY_MODEL_ID) return;

    if (!event.payload.permanent) return;

    await this.cleanupService.cleanup(entry.entryId);
  }
}

export default EntryAfterDeleteEventHandler.createImplementation({
  implementation: CleanupOnEntryDeleteHandler,
  dependencies: [CleanupService]
});

Event Naming Conventions

Registration

YOU MUST include the full file path with the .ts extension in the src prop. For example, use src={"@/extensions/my-handler.ts"}, NOT src={"@/extensions/my-handler"}. Omitting the file extension will cause a build failure.

YOU MUST use export default for the createImplementation() call when the file is targeted directly by an Extension src prop. Using a named export (export const Foo = SomeFactory.createImplementation(...)) will cause a build failure. Named exports are only valid inside files registered via createFeature.

<Api.Extension src={"@/extensions/my-handler.ts"} />

Deploy with: yarn webiny deploy api --env=dev

Resolving Types (MANDATORY)

Before writing any code that accesses event payload properties or domain types (CmsEntry, CmsModel, etc.), you MUST read the source file listed in the catalog's Source field to verify the exact property names and types. Do not assume or guess property names from memory.

1. Read the abstractions.ts file from the catalog Source path — it contains the payload interface
2. Read the events.ts file (sibling to abstractions.ts) — it contains the Interface and Event types
3. If the payload references domain types, follow the import and read that declaration

Key Rules

• Before handlers: payload may be mutable — write to it to set computed fields. Throw to reject the operation.
• After handlers: payload reflects persisted state — do not mutate. Use for side effects.
• Filter by entity: handlers fire for ALL entities of that type. Always check modelId, entity type, etc.
• Events extend DomainEvent<TPayload> with eventType property (not static type)
• Every event must implement getHandlerAbstraction() returning its handler abstraction
• Every handler abstraction must have a namespace with Interface and Event types
• Payload types live in abstractions.ts; event classes live in events.ts
• Publish order: before event → operation → after event
• DI constructor parameter order must match the dependencies array order exactly
• Use .js extensions in import paths (ES modules)

Related Skills

• webiny-api-architect — Architecture overview, Services vs UseCases, feature naming
• webiny-use-case-pattern — UseCase implementation where events are published from
• webiny-dependency-injection — Injectable services catalog