Event integrations

Active contributors: dirt (data insights & reporting) team.

Purpose

Event integrations let an organisation forward audit events to its own observability tools — Slack, Microsoft Teams, generic webhooks, Splunk HEC, Datadog, and similar. Conceptually, every audit event written to the Event table is also evaluated against the per-organization integration configurations, and matching events are formatted and dispatched to the configured destination.

Despite the name, this code lives under src/Core/Dirt/EventIntegrations/ rather than AdminConsole, because the Dirt team owns the entire reporting / event surface.

Directory layout

src/Core/Dirt/EventIntegrations/
├── EventIntegrationsServiceCollectionExtensions.cs   # ~31KB of registration glue
├── README.md                                         # 36KB design doc covering the integration model
├── OrganizationIntegrationConfigurations/            # Domain entities + commands for the configuration side
└── OrganizationIntegrations/                         # The actual integration implementations
    ├── Slack/
    ├── Teams/
    ├── Webhook/
    ├── HEC/   (Splunk HTTP Event Collector)
    ├── Datadog/
    └── ...

The high-level README.md in this folder is the canonical design doc; it explains how integrations are configured, scoped, and dispatched. This wiki page summarises the moving parts.

Key abstractions

Concept	Description
OrganizationIntegration	A row that says "for this org, deliver matching events to this destination".
OrganizationIntegrationConfiguration	The destination-specific config (Slack channel ID, webhook URL, HEC token, etc.).
IIntegrationFilterService	Decides whether a given Event should be forwarded for a given integration (per-event-type allow lists, target ID match).
IIntegrationPublishHandler	Per-destination implementation that formats the event and POSTs / publishes it. One per supported destination (SlackPublishHandler, WebhookPublishHandler, HECPublishHandler, …).
IEventIntegrationCommand / Query	Domain commands for adding / updating / deleting integrations.

EventIntegrationsServiceCollectionExtensions is the single registration point — services.AddEventIntegrationsCommandsQueries(globalSettings) (called from Api.Startup). It wires the publishers, the configuration repositories, the filter, and the per-destination HTTP clients.

How it works

sequenceDiagram
    participant Api
    participant EventService
    participant Filter as IIntegrationFilterService
    participant Pub as IIntegrationPublishHandler

    Api->>EventService: LogCipherEventAsync(...)
    EventService->>EventService: persist Event
    EventService->>Filter: should this go to any integration?
    Filter-->>EventService: list of matching integrations
    EventService->>Pub: Publish for each integration
    Pub->>External["Slack / Teams / Webhook / HEC / Datadog"]

In production, the publish path is async — events are queued and pushed by a background dispatcher so the request that triggered the event isn't blocked.

Configuration

Integrations are managed through:

• The Api/AdminConsole/Public/ org-level public API.
• The Web Vault's organization integrations UI.
• Commercially-licensed feature gates (the more advanced integrations require a Teams / Enterprise plan).

Configuration is stored encrypted (data-protected) in OrganizationIntegrationConfiguration rows.

Related areas

• The Slack-specific OAuth flow (Bit.Core.Dirt.EventIntegrations.OrganizationIntegrations.Slack/) uses Slack's app-installation flow; tokens land in OrganizationIntegrationConfiguration.
• Teams integration uses webhook URLs.
• The webhook destination supports both classic webhooks and signed payloads (HMAC).

Entry points for modification

• New destination → implement IIntegrationPublishHandler, add the configuration shape, register both via EventIntegrationsServiceCollectionExtensions, and add a UI surface in Api/AdminConsole/Public/Controllers/IntegrationsController.cs.
• New event-type filter rule → extend IIntegrationFilterService.
• Tighten retries / timeouts → adjust the typed HTTP clients in EventIntegrationsServiceCollectionExtensions.

For the ingest side of audit events see apps/events and apps/events-processor.