Event System | VexAI Docs

Event Bus Architecture

The event bus is the central hub that receives every event produced across the bot. Listeners subscribe with filters, and when an incoming event matches, the associated action fires.

ℹ️ How It Works

Events flow through a single bus: Source → Bus → Filter Match → Action. Each listener has its own cooldown to prevent accidental spam loops.

Central event bus receives events from all five sources.
Listeners subscribe with type and field filters.
Matched events trigger the listener's configured action.
Rate limiting per listener prevents repeated firing.

Event Sources

VexAI ingests events from five distinct sources. Each source produces typed event payloads that flow into the central bus.

1. Discord Events

Native Discord gateway events captured by discord.js. These are the most common source of events.

Event	Description
`message`	New message in any channel
`reaction`	Reaction added or removed
`member_join`	User joins the server
`member_leave`	User leaves the server
`role_change`	Role added or removed from a member
`channel_change`	Channel created, updated, or deleted
`thread_change`	Thread created, archived, or deleted

Each event includes rich context: user, channel, guild, content, timestamps, and more.

2. Webhook Events

Inbound HTTP payloads from external services are parsed and emitted as events.

Provider	Event Types
GitHub	`push`, `pull_request`, `issues`, `release`, `workflow_run`
GitLab	`push`, `merge_request`, `pipeline`, `issue`
Generic	Any JSON payload, matched by custom field conditions

3. WebSocket Events

Persistent WebSocket connections to external services. Events are emitted on connection lifecycle changes and incoming messages.

ws_connect: Connection established
ws_message: Message received
ws_disconnect: Connection lost (automatic reconnection is attempted)

💡 Reconnection

WebSocket connections automatically attempt to reconnect with exponential backoff when the remote end drops the connection.

4. REST Polling

Poll any REST API on a configurable schedule. Events are emitted only when the response changes, making it ideal for monitoring external services.

Configurable poll interval
Change detection: compares current response to previous and only emits when data differs
Supports all HTTP methods and custom headers

ℹ️ Change Detection

REST polls store the last response hash. An event fires only when the new response differs, so you won't be flooded with duplicate events from static endpoints.

5. Cron Events

Time-based triggers using standard cron expressions. Use these for scheduled tasks that don't depend on external input.

# Every day at 9 AM
0 9 * * *

# Every 30 minutes
*/30 * * * *

# Weekdays at 6 PM
0 18 * * 1-5

Listener Configuration

Each listener is a subscription to the event bus. It declares which events it cares about and what to do when one arrives.

⚠️ Listener Scope

Listeners are scoped to the guild where they are created. A listener in Guild A will never fire for events in Guild B.

Every listener specifies:

Event source: which of the 5 sources to listen on
Event type filter: the specific event type (e.g. message, push)
Field conditions: optional filters on event payload fields
Action: what to do when the event matches
Cooldown: minimum interval between triggers

Filtering

Filters narrow which events trigger a listener. Combine multiple conditions for precise targeting.

Filter Operators

Filter Type	Description	Example
`equals`	Exact match on a field value	`user.id equals "123"`
`contains`	Substring match	`content contains "deploy"`
`regex`	Regular expression match	`content regex "^!\\w+"`
`gt`	Greater than (numeric)	`memberCount gt 100`
`lt`	Less than (numeric)	`age lt 30`
`exists`	Field exists in payload	`attachments exists true`

Filterable Fields

In addition to custom payload fields, every event supports these built-in filters:

Event type: message, push, ws_message, etc.
Event source: discord, webhook, websocket, rest, cron
Guild ID: restrict to a specific server
Channel ID: restrict to a specific channel
User ID: restrict to events from a specific user

Listener Actions

When a listener's filters match, one of these actions executes:

Action	Description
Post message	Send a templated message to a target channel. Supports variable interpolation from the event payload.
AI generate	Send the event context to the LLM and post the generated response. Useful for auto-summarisation or smart replies.
Execute tool	Run any registered VexAI tool (from any skill). Passes event data as tool arguments.
Forward webhook	POST the event payload to an external webhook URL.

💡 Template Variables

The "Post message" action supports {{event.field}} placeholders that are replaced with values from the event payload at runtime.

Rate Limiting

Every listener has a configurable cooldown, which is the minimum time that must elapse between successive triggers. If an event matches during the cooldown window, it is silently discarded.

⚠️ Prevent Loops

If a listener's action produces an event that matches the same listener (e.g. a "Post message" action triggering a "message" event), the cooldown is your first line of defence against infinite loops. Always set a reasonable cooldown.

Event System Tools

The event-system skill exposes 13 tools for managing every aspect of event routing:

Listener Management

Tool	Description
`create_event_listener`	Create a new listener with source, filters, and action
`edit_event_listener`	Modify an existing listener's configuration
`delete_event_listener`	Remove a listener
`list_event_listeners`	List all listeners (optionally filtered by source)
`toggle_event_listener`	Enable or disable a listener without deleting it

WebSocket Connections

Tool	Description
`connect_websocket`	Open a persistent WebSocket connection
`disconnect_websocket`	Close a WebSocket connection
`list_websockets`	List active WebSocket connections

REST Polling

Tool	Description
`create_rest_poll`	Register a REST endpoint to poll on a schedule
`delete_rest_poll`	Stop polling a REST endpoint
`list_rest_polls`	List all active REST polls

Utilities

Tool	Description
`emit_event`	Manually emit a custom event into the bus
`view_event_log`	View the recent event log with timestamps and matched listeners