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.
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.
{Entity}Before{Operation}EventHandler — fires before persistence, can validate/transform/reject{Entity}After{Operation}EventHandler — fires after persistence, for side effectsinterface SomeEventHandler.Interface {
handle(event: SomeEventHandler.Event): Promise<void>;
}
The Event is a DomainEvent<Payload> where the payload contains the entity and input data.
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.
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.
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]
});
When your feature needs to notify other parts of the system about important domain actions, define your own events.
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;
}
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;
}
}
// 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]
});
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]
});
| Artifact | Pattern | Example |
|---|---|---|
eventType | "entity.beforeAction" / "entity.afterAction" | "tenant.beforeDisable" |
| Handler abstraction | {Entity}{Before|After}{Action}EventHandler | TenantBeforeDisableEventHandler |
| Event class | {Entity}{Before|After}{Action}Event | TenantBeforeDisableEvent |
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
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.
abstractions.ts file from the catalog Source path — it contains the payload interfaceevents.ts file (sibling to abstractions.ts) — it contains the Interface and Event typesmodelId, entity type, etc.DomainEvent<TPayload> with eventType property (not static type)getHandlerAbstraction() returning its handler abstractionInterface and Event typesabstractions.ts; event classes live in events.tsdependencies array order exactly.js extensions in import paths (ES modules)