EventHandler Pattern

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