Event Bus System

Relevant source files

The following files were used as context for generating this wiki page:

• packages/cli/src/eventbus/message-event-bus/message-event-bus.ts
• packages/cli/src/eventbus/event-message-classes/event-message-execution.ts
• packages/cli/src/eventbus/message-event-bus-destination/message-event-bus-destination-webhook.ee.ts
• packages/@n8n/config/src/configs/event-bus.config.ts
• packages/cli/src/eventbus/message-event-bus-destination/message-event-bus-destination-factory.ts
• packages/cli/src/eventbus/message-event-bus-destination/message-event-bus-destination-base.ts
• packages/cli/src/eventbus/event-message-classes/event-message-workflow.ts
• AGENTS.md

The Event Bus system provides a mechanism for decoupled, event-driven communication within the n8n backend. Its primary purpose is to allow different parts of the application to publish events (such as workflow execution status changes) without being tightly coupled to the subscribers that consume these events. This architecture allows for extensible integrations, where events can be sent to various destinations like webhooks, logging services, or message queues.

The system is designed to be configurable, allowing administrators to enable or disable it, specify which events to listen for, and define the destinations where these events should be sent.

Sources: AGENTS.md:46-46, packages/cli/src/eventbus/message-event-bus/message-event-bus.ts:16-21

Architecture Overview

The Event Bus system follows a classic publish-subscribe pattern. When an event occurs in the application (e.g., a workflow execution finishes), it is published to the MessageEventBus. The bus then iterates through a list of configured destinations and forwards the event message to each one that is subscribed to that specific event type.

This diagram illustrates the high-level data flow from event creation to publishing at a destination.

Configuration

The Event Bus system is configured through environment variables, which are defined in the EventBusConfig. The system is disabled by default.

Sources: packages/@n8n/config/src/configs/event-bus.config.ts

Parameter	Type	Description	Default
N8N_EVENT_BUS_ENABLED	boolean	Enables or disables the entire event bus system.	false
N8N_EVENT_BUS_EVENTS	string	A comma-separated list of events to publish. Use * to publish all events.	''
N8N_EVENT_BUS_DESTINATIONS	string	A comma-separated list of destination names to enable.	''
N8N_EVENT_BUS_WEBHOOK_URL	string	The URL for the webhook destination. Required if webhook is in the destinations list.	''
N8N_EVENT_BUS_WEBHOOK_AUTHORIZATION_HEADER	string	The value for the Authorization header sent with webhook requests.	''
N8N_EVENT_BUS_WEBHOOK_IGNORE_TLS_ERROR	boolean	If true, TLS/SSL certificate errors will be ignored for webhook requests.	false

Sources: packages/@n8n/config/src/configs/event-bus.config.ts:8-51

Core Components

MessageEventBus

The MessageEventBus is the central component of the system. It is a singleton responsible for initializing destinations and publishing events.

• init(): This method is called on application startup. It reads the configuration, and if the event bus is enabled, it uses the MessageEventBusDestinationFactory to create instances of all configured destinations.
• publish(message: EventMessage): This method takes an EventMessage object. It first checks if the event type of the message is enabled in the configuration. If it is, the bus iterates through all initialized destinations and calls their respective publish methods.

Sources: packages/cli/src/eventbus/message-event-bus/message-event-bus.ts:31-66

The following sequence diagram shows the process of publishing an event.

Event Messages

Events are represented by classes that extend the base EventMessage class. Each message contains the event payload and metadata.

This diagram shows the inheritance structure for event messages.

• EventMessage: The abstract base class for all event messages. It defines the common structure, including type, payload, timestamp, instanceId, and context.
• EventMessageExecution: An event message for workflow executions. The type is hardcoded to 'execution', and the payload contains the full execution object.
• EventMessageWorkflow: An event message for workflow events (e.g., created, updated). The type is 'workflow'.

Sources: packages/cli/src/eventbus/event-message-classes/event-message-execution.ts:10-25, packages/cli/src/eventbus/event-message-classes/event-message-workflow.ts:10-25

Destinations

Destinations are responsible for sending event messages to external systems. All destinations must implement the IMessageEventBusDestination interface, which is typically done by extending the MessageEventBusDestinationBase class.

Sources: packages/cli/src/eventbus/message-event-bus-destination/message-event-bus-destination-base.ts:10-12

Destination Factory

The MessageEventBusDestinationFactory is a simple factory responsible for creating instances of destination classes based on a string identifier. It maintains a map of known destination types.

Sources: packages/cli/src/eventbus/message-event-bus-destination/message-event-bus-destination-factory.ts:17-25

Webhook Destination

MessageEventBusDestinationWebhook is a concrete implementation that sends event messages to a configured URL via an HTTP POST request.

• init(): Initializes the destination by creating an axios instance. It configures the base URL, authorization header, and TLS/SSL verification based on the application configuration.
• publish(message: EventMessage): Sends the provided message as the body of an HTTP POST request to the configured webhook URL. It logs the success or failure of the request.

Sources: packages/cli/src/eventbus/message-event-bus-destination/message-event-bus-destination-webhook.ee.ts:27-66

The following code snippet shows the core logic of the webhook's publish method.

// packages/cli/src/eventbus/message-event-bus-destination/message-event-bus-destination-webhook.ee.ts:56-65
public async publish(message: EventMessage): Promise<void> {
    try {
        await this.axios!.post('', message);
        Logger.debug(`Published event via webhook`, {
            instanceId: this.instanceId,
        });
    } catch (error) {
        Logger.error(`Failed to publish event via webhook`, {
            error: error as Error,
            instanceId: this.instanceId,
        });
    }
}