EventHandler Pattern

What It Is

An EventHandler reacts to domain events in the Webiny lifecycle (e.g.,

EntryBeforeCreateEventHandler

TenantAfterDeleteEventHandler

handle

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

DomainEvent<Payload>

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

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

events.ts

// 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

eventType

"entity.beforeAction"

"entity.afterAction"

"tenant.beforeDisable"

{Entity}{Before|After}{Action}EventHandler

TenantBeforeDisableEventHandler

{Entity}{Before|After}{Action}Event

TenantBeforeDisableEvent

Registration

YOU MUST include the full file path with the

.ts

src

src={"@/extensions/my-handler.ts"}

src={"@/extensions/my-handler"}

YOU MUST use

export default

createImplementation()

src

export const Foo = SomeFactory.createImplementation(...)

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

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