Event Routing & Dispatching
Relevant source files
The following files were used as context for generating this wiki page:
Event Routing and Dispatching is a system within Hoop designed to capture platform events (such as session starts, data masking alerts, or guardrail violations) and route them to external or internal consumers. The system allows administrators to define "Subscriptions" that map specific event types to actions, primarily the execution of parameterized Runbooks.
The system encompasses a centralized event catalog, a subscription management interface, and a dispatcher that handles the execution logic, including parameter mapping from event payloads to Runbook inputs. Sources: gateway/events/catalog.go, gateway/eventrouting/dispatcher.go:1-15, webapp_v2/src/pages/EventRouting/Form/index.jsx:110-140
System Architecture
The Event Routing architecture follows a producer-consumer pattern where the Gateway identifies events and dispatches them based on stored subscription rules.
Event Processing Flow
The following diagram illustrates the flow from an event occurring in the gateway to the execution of a routed runbook.
The dispatcher loads the context for a specific dispatch, validates the subscription status, renders parameters from the event payload, and triggers a client execution. Sources: gateway/eventrouting/dispatcher.go:17-60
Event Catalog
Hoop maintains a structured catalog of event types. Each event belongs to a category and defines a schema for its payload, ensuring that dispatchers can reliably map data to runbook parameters.
Key Event Categories
| Category | Description | Example Event Types |
|---|---|---|
| Alert | Security and DLP related notifications | alert.sensitive_data_detected, alert.data_masked |
| Access | Just-In-Time (JIT) access lifecycle | access.jit_approved, access.jit_denied |
| Session | Session lifecycle and policy violations | session.started, session.closed, session.guardrail_violation |
Sources: gateway/events/catalog.go:21-170
Event Schema Structure
Each EventType in the catalog includes:
- Name/Category: Unique identifiers.
- Schema: A list of
SchemaFieldobjects (Name, Type, Required status). - Sample Payload: Example data for testing and UI previews.
Sources: gateway/events/catalog.go:5-19
Subscription & Parameter Mapping
Subscriptions define the link between an event and a target Runbook. A critical component of this link is the Parameter Mapping, which uses JSONPath-style syntax (e.g., $.session_id) to extract values from an event payload and inject them into Runbook arguments. Sources: webapp_v2/src/pages/EventRouting/Form/index.jsx:215-235, webapp_v2/src/services/eventRouting.js:65-75
Dispatch Logic
When a dispatch is processed (processDispatch), the system performs several validation and preparation steps:
- Subscription Validation: Ensures the subscription is
active. - Parameter Rendering: Uses
events.RenderParametersto mapsub.ParameterMappingagainstevent.Payload. - Connection Retrieval: Loads the target connection and verifies it has an assigned
AgentID. - Runbook Fetching: Retrieves the runbook file from the configured Git repository.
- Execution: Creates a
clientexecinstance, impersonating the subscription creator, and runs the runbook.
Sources: gateway/eventrouting/dispatcher.go:17-85
Dispatcher Execution Lifecycle
The dispatcher handles the actual execution of the routed runbook via a dedicated execution client.
The dispatcher has a hardcoded execution timeout of 60 seconds. If the runbook execution exceeds this limit, the dispatch is failed. Sources: gateway/eventrouting/dispatcher.go:15, gateway/eventrouting/dispatcher.go:90-115
Webhook Integration
In addition to internal Runbook routing, Hoop supports external routing via webhooks (Svix). This is used to notify external platforms like Microsoft Teams when specific events occur, such as a review being created. Sources: gateway/transport/plugins/webhooks/webhooks.go:120-150
Webhook Event Processing
| Event Type | Logic |
|---|---|
pbagent.SessionOpen | Processes session metadata and review inputs for external notification. |
pbclient.SessionClose | Captures exit codes and errors for delivery to webhooks. |
ReviewCreate | Generates Adaptive Cards for Microsoft Teams, including facts and code snippets. |
Sources: gateway/transport/plugins/webhooks/webhooks.go:98-118, gateway/transport/plugins/webhooks/webhooks.go:153-200
Conclusion
The Event Routing & Dispatching system provides a flexible framework for automating infrastructure responses to platform events. By combining a strictly defined Event Catalog with a dynamic Parameter Mapping engine and Runbook execution, Hoop enables complex security and operational workflows, such as auto-revoking access upon PII detection or notifying teams of guardrail violations in real-time.