fix: restore typed EventSchema discriminated union dispatcher

[gjtorikian]

Summary

A user reported that the previous typed events in v5 were lost on the major upgrade. This PR restores them.

• EventSchema is now a dispatcher class rather than a flat dataclass with data: Dict[str, Any]
• EventSchema.from_dict() reads the event field and routes to the correct typed variant (e.g. DsyncUserCreated, UserCreated)
• Added EventSchemaVariant = Union[ActionAuthenticationDenied, ..., VaultNamesListed] covering all 95 event types
• events.list_events() returns SyncPage[EventSchemaVariant] / AsyncPage[EventSchemaVariant]
• webhooks.verify_event() and _verification.verify_event() return EventSchemaVariant
• Round-trip tests for EventSchema removed (dispatcher has no to_dict()); webhook verification fixture updated with a complete User payload

Test plan

• uv run nox -s ci passes (1908 tests, lint, type check, format)
• workos.events.list_events() — each item is a fully-typed variant (e.g. DsyncUserCreated with data: DirectoryUser)
• workos.webhooks.verify_event() — returns the correct variant for the event type in the payload
• Unknown event types return EventSchemaUnknown with the raw payload preserved. Missing or None discriminator raises WorkOSError.

🤖 Generated with Claude Code

[greptile-apps]

Greptile Summary

This PR restores typed event dispatching that was lost in the v5 upgrade. EventSchema is converted from a flat dataclass to a pure dispatcher whose from_dict() reads the event discriminator and routes to one of 95 typed variants (or EventSchemaUnknown for unrecognized types). All public API points — list_events(), verify_event() — now return EventSchemaVariant. The implementation is clean and the core logic is correct.

Confidence Score: 5/5

This PR is safe to merge; no P0 or P1 issues found.

All findings are P2 or lower. The dispatcher logic is correct: _raise_deserialize_error is NoReturn so there are no implicit None returns; each variant model's from_dict receives the full event dict as expected; unknown events gracefully fall back to EventSchemaUnknown; tests cover dispatch, unknown fallback, and error cases.

No files require special attention.

Important Files Changed

Filename	Overview
src/workos/events/models/event_schema.py	Core dispatcher: EventSchema converted to a routing class; EventSchemaUnknown and EventSchemaVariant union added. Logic is correct — _raise_deserialize_error is NoReturn, dispatch fallthrough to unknown is safe.
src/workos/webhooks/_verification.py	Return type updated to EventSchemaVariant; EventSchemaVariant is only imported under TYPE_CHECKING (safe due to from future import annotations), consistent with docstring update.
src/workos/events/_resource.py	cast() wrapping used to bridge EventSchema dispatcher (which pagination calls from_dict on) to EventSchemaVariant return type; type: ignore[arg-type] is correctly scoped.
tests/test_webhook_verification.py	Fixture updated with full User payload required by UserCreated.from_dict; assertions switched from EventSchema to UserCreated; all verification paths covered.
tests/test_models_round_trip.py	Round-trip tests for EventSchema (which no longer has to_dict()) removed; replaced by TestDiscriminatorDispatch covering known dispatch, unknown fallback, and error cases.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Raw event dict / webhook payload] --> B{EventSchema.from_dict}
    B --> C{"'event' key present?"}
    C -- No --> D[_raise_deserialize_error\nMissing required field]
    C -- Yes --> E{"event value is None?"}
    E -- Yes --> F[_raise_deserialize_error\nevent must not be None]
    E -- No --> G{_DISPATCH.get\ndiscriminator value}
    G -- Known key --> H[dispatch_cls.from_dict\ne.g. UserCreated, DsyncUserCreated]
    G -- Unknown key --> I[EventSchemaUnknown.from_dict\nraw_data preserved]
    H --> J[EventSchemaVariant]
    I --> J
    J --> K[list_events → SyncPage / AsyncPage]
    J --> L[verify_event → EventSchemaVariant]

Loading

_{Reviews (5): Last reviewed commit: "fix: tighten event dispatch types and te..." | Re-trigger Greptile}

[gjtorikian]

@greptile review