Event Forwarder - GrowthBook Documentation

GrowthBook offers a fully managed event ingestion pipeline. Use our SDKs to track events in your app and we will enrich and forward them to your data warehouse in near real-time.

Benefits

Fully Managed: No need to worry about infrastructure management, scaling, or maintenance.
Seamless Integration: Built-in tracking in our SDKs.
Near Real-Time: Events are available in your warehouse typically within a few seconds.
Broad Support: Works with BigQuery, Snowflake, and Databricks today, with more warehouses coming soon.

How it Works

Provide GrowthBook with your data warehouse connection details (see Connection Permissions for required permissions)
We will create destination tables for events, experiment_viewed, and feature_usage
You send analytics events to our scalable Ingestion API
We enrich the events and stream them into your warehouse within seconds
We will build a Fact Table, customize the Data Source’s experiment assignment queries, and feature usage queries, so you can quickly start analyzing your experiment data and defining metrics.

Connection Permissions

When setting up the Event Forwarder, GrowthBook uses your data warehouse connection to pre-create destination tables and validate write access.

BigQuery

The service account configured in your GrowthBook BigQuery datasource must have the BigQuery Data Editor role on the destination dataset. This grants the necessary permissions to:

Check whether destination tables exist
Create the destination tables (events, experiment_viewed, feature_usage)
Write data via the BigQuery Storage Write API

You can grant this at the dataset level in the BigQuery console or via the roles/bigquery.dataEditor IAM role binding.

Snowflake

The Snowflake connection must use key-pair authentication — password authentication is not supported for the Event Forwarder. GrowthBook creates the three destination tables itself during setup, then streams events into them through Snowpipe Streaming as the connection’s user. Snowpipe Streaming runs under the user’s default role, so the role you enter in the Event Forwarder must be that user’s default role (ALTER USER <user> SET DEFAULT_ROLE = <role>). Setup creates the tables and checks them as that same role, so it needs the following privileges: CREATE TABLE and CREATE SCHEMA are required because we use Snowpipe Streaming with schema evolution, which may create or alter tables and schemas as your event schema changes. Key-pair authentication must be configured on the Snowflake datasource connection itself — it is not set in the Event Forwarder UI. Update your datasource’s connection settings to use key-pair auth before enabling the Event Forwarder.

Databricks

Before you start: is Zerobus available for your workspace?

The Databricks Event Forwarder writes through Zerobus Ingest, which is not available everywhere yet. Check three things:

Region. Open the workspace switcher in the top navigation bar to see your workspace region, then confirm it has a check in the Zerobus Ingest column of Databricks’ availability table for your cloud: AWS, Azure, Google Cloud.
Unity Catalog. Zerobus writes only to Unity Catalog managed tables. The catalog on your GrowthBook connection must be a Unity Catalog catalog, not hive_metastore.
Databricks OAuth (machine-to-machine) on the connection, as described below.

Setup creates the tables through your SQL warehouse and does not test Zerobus itself. If your region is unsupported, setup succeeds and the forwarder shows an error after the first event arrives. The Databricks connection must use Databricks OAuth (machine-to-machine) authentication with a Databricks-issued client ID and secret. Personal access tokens keep working for queries, but the Event Forwarder writes through Zerobus Ingest, which only accepts Databricks OAuth tokens. Switch the datasource connection to Databricks OAuth before enabling the Event Forwarder. Grant the service principal the following on the destination catalog and schema. GrowthBook creates the three Delta tables itself, so it also gets SELECT and MODIFY on them as their owner.

GRANT USE CATALOG ON CATALOG <catalog> TO `<service-principal-application-id>`;
GRANT USE SCHEMA, CREATE TABLE ON SCHEMA <catalog>.<schema> TO `<service-principal-application-id>`;

In the Event Forwarder UI you provide:

Catalog, pre-filled from your connection when it names one.
Schema, an existing schema the service principal can create tables in. We suggest a dedicated one such as growthbook.
Table prefix (optional, default gb). GrowthBook creates <prefix>_events, <prefix>_experiment_viewed, and <prefix>_feature_usage in that schema, clustered on received_at, with attributes and properties stored as VARIANT.
Zerobus endpoint for your workspace. See Finding your Zerobus endpoint below.

Finding your Zerobus endpoint

The endpoint is not shown in the Databricks UI; you build it from two values:

Cloud	Endpoint
AWS	`https://<workspace-id>.zerobus.<region>.cloud.databricks.com`
Azure	`https://<workspace-id>.zerobus.<region>.azuredatabricks.net`
Google Cloud	`https://<workspace-id>.zerobus.<region>.gcp.databricks.com`

Workspace ID is the long number in your workspace URL. On AWS and Google Cloud it follows ?o= (for example https://dbc-a1b2c3d4-e5f6.cloud.databricks.com/?o=1234567890123456). On Azure it follows adb- in the hostname (https://adb-1234567890123456.7.azuredatabricks.net). GrowthBook pre-fills it where the connection host carries it.
Region is the cloud region your workspace runs in, for example us-east-1, eastus, or us-central1. It is shown in the Databricks account console under Workspaces.

Zerobus Ingest is a serverless Databricks feature billed to your Databricks account per GB ingested. No SQL warehouse or cluster runs on your side to receive events; the SQL warehouse configured on the datasource is only used to create the tables and to run your experiment queries.

Network Access

For Event Forwarder, you must always allow incoming connections from GrowthBook Cloud’s primary ip address (52.70.79.40/32). If you are using our eu-west-1 ingestor region, you also must allow traffic from 54.74.233.97/32.

Get Started

The event forwarder is an advanced Pro/Enterprise feature and must be enabled for your account. Contact your account manager or reach out to sales@growthbook.io to learn more and get started.

Sending Events

There are 2 ways to send events to GrowthBook:

With our SDKs
With our Ingestion API

With SDKs

These SDKs have a built-in plugin that automatically sends feature usage and experiment view events to GrowthBook, with the SDK’s attributes as context. Don’t include sensitive information in your attributes (or anonymize it first). For other SDKs, use the Ingestion API below.

Add data-tracking="growthbook" to the script tag. It reports events that already fired; it does not enroll users in an experiment.

<script async
  data-client-key="YOUR_CLIENT_KEY"
  data-tracking="growthbook"
  data-event-ingestor-host="https://us-east-1.gb-ingest.com"
  src="https://cdn.jsdelivr.net/npm/@growthbook/growthbook/dist/bundles/auto.min.js"
></script>

Push custom events to the window.gbEvents array:

<script>
  window.gbEvents = window.gbEvents || [];

  // Without properties
  window.gbEvents.push("Page View");

  // With properties
  window.gbEvents.push({
    eventName: "Button Click",
    properties: { button: "Sign Up" },
  });
</script>

Attribute	Description
`data-event-ingestor-host`	Ingestor for your Data Region.
`data-event-transport`	`auto` (default), `beacon`, or `fetch`, like the JavaScript SDK’s `transport` option.

Requires @growthbook/growthbook v1.4.0 or later. We recommend also adding autoAttributesPlugin to include common attributes (browser, session_id, UTM parameters, etc.) with every event.

import { GrowthBook } from "@growthbook/growthbook";
import {
  autoAttributesPlugin,
  growthbookTrackingPlugin,
} from "@growthbook/growthbook/plugins";

const gb = new GrowthBook({
  clientKey: "YOUR_CLIENT_KEY",
  plugins: [
    autoAttributesPlugin(),
    growthbookTrackingPlugin({
      ingestorHost: "https://us-east-1.gb-ingest.com",
    }),
  ],
});

Log custom events with logEvent. In React, get the instance with useGrowthBook().

// Without properties
gb.logEvent("Page View");

// With properties
gb.logEvent("Button Click", { button: "Sign Up" });

Option	Description
`ingestorHost`	Ingestor for your Data Region.
`enableFeatureUsageEvents`	Set to `false` to stop sending feature usage events. Default `true`. v1.8.0+.
`transport`	`auto` (default), `beacon`, or `fetch`. See below. v1.7.0+.

Events are batched and sent with fetch using keepalive. When the page is hidden or unloading, the queue is flushed with navigator.sendBeacon. Both survive the page being torn down, so exposures aren’t lost when a user navigates away immediately, which matters most for redirect experiments. Set transport: "beacon" to always prefer sendBeacon, or "fetch" to never use it.

Requires @growthbook/growthbook v1.7.0 or later.

import { GrowthBookClient } from "@growthbook/growthbook";
import { growthbookTrackingPlugin } from "@growthbook/growthbook/plugins";

const gb = new GrowthBookClient({
  clientKey: "YOUR_CLIENT_KEY",
  plugins: [
    growthbookTrackingPlugin({
      ingestorHost: "https://us-east-1.gb-ingest.com",
    }),
  ],
});

Log custom events with logEvent, passing the user context:

gb.logEvent("Sign Up", { accountPlan: "pro" }, userContext);

User-scoped instances (for example req.growthbook from the Express middleware) don’t need the user context:

req.growthbook.logEvent("Sign Up", { accountPlan: "pro" });

Set enableFeatureUsageEvents: false (v1.8.0+) to stop sending feature usage events.

Requires growthbook v2.2.0 or later, plus the requests package:

pip install growthbook requests

from growthbook import GrowthBook, GrowthBookTrackingPlugin

gb = GrowthBook(
    client_key="YOUR_CLIENT_KEY",
    attributes={"id": "user_123"},
    plugins=[
        GrowthBookTrackingPlugin(
            ingestor_host="https://us-east-1.gb-ingest.com",
        )
    ],
)
gb.load_features()

Log custom events with log_event:

gb.log_event("Button Click", {"button": "Sign Up"})

Call gb.destroy() when you’re done with the instance to flush pending events.

Option	Description
`ingestor_host`	Ingestor for your Data Region.
`track_feature_evaluated`	Set to `False` to stop sending feature usage events. Default `True`.
`batch_size`	Events to queue before sending. Default `10`.
`batch_timeout`	Seconds to wait before sending a partial batch. Default `10.0`.

Use the GrowthBook class. The async GrowthBookClient does not send events to GrowthBook yet.

Requires growthbook/growthbook v2.4.0 or later.

use Growthbook\Growthbook;
use Growthbook\GrowthBookTrackingPlugin;
use Growthbook\GrowthBookTrackingPluginConfig;

$growthbook = Growthbook::create()
  ->withAttributes(['id' => $userId])
  ->addPlugin(new GrowthBookTrackingPlugin(
    new GrowthBookTrackingPluginConfig(
      ingestorHost: "https://us-east-1.gb-ingest.com",
    )
  ));

$growthbook->initialize("YOUR_CLIENT_KEY");

Call addPlugin() after any with*() methods. Those return a copy of the instance, and a discarded copy closes the plugin. The plugin gets its client key from initialize(), and pending events are sent when the request ends.Custom events aren’t supported yet. Send them with the Ingestion API.

Option	Description
`ingestorHost`	Ingestor for your Data Region.
`batchSize`	Events to queue before sending mid-request. Default `100`.

Requires github.com/growthbook/growthbook-golang v0.5.0 or later.

import (
    "context"

    gb "github.com/growthbook/growthbook-golang"
)

client, err := gb.NewClient(
    context.Background(),
    gb.WithClientKey("YOUR_CLIENT_KEY"),
    gb.WithSseDataSource(),
    gb.WithGrowthBookTracking(gb.TrackingPluginConfig{
        IngestorHost: "https://us-east-1.gb-ingest.com",
    }),
)
if err != nil {
    // handle error
}
defer client.Close() // sends pending events

Log custom events with LogEvent, on a client scoped to the current user. Don’t call Close() on that client; it closes the shared plugin.

userClient, _ := client.WithAttributes(gb.Attributes{"id": "user-123"})

userClient.LogEvent(context.Background(), "Button Click", gb.EventProperties{"button": "Sign Up"})

Option	Description
`IngestorHost`	Ingestor for your Data Region.
`BatchSize`	Events to queue before sending. Default `100`.
`BatchTimeout`	How long to wait before sending a partial batch. Default `10s`.

Requires the GrowthBook Java SDK v0.11.1 or later.

import growthbook.sdk.java.multiusermode.GrowthBookClient;
import growthbook.sdk.java.multiusermode.configurations.Options;
import growthbook.sdk.java.multiusermode.configurations.UserContext;
import growthbook.sdk.java.plugin.tracking.GrowthBookTrackingPlugin;
import growthbook.sdk.java.plugin.tracking.TrackingPluginConfig;
import java.util.Collections;

String clientKey = "YOUR_CLIENT_KEY";

GrowthBookTrackingPlugin trackingPlugin = GrowthBookTrackingPlugin.of(
    TrackingPluginConfig.builder()
        .clientKey(clientKey)
        .ingestorHost("https://us-east-1.gb-ingest.com")
        .build()
);

GrowthBookClient client = new GrowthBookClient(
    Options.builder()
        .apiHost("https://cdn.growthbook.io")
        .clientKey(clientKey)
        .plugins(Collections.singletonList(trackingPlugin))
        .build()
);

if (!client.initialize()) {
    client.shutdown();
    throw new IllegalStateException("GrowthBook initialization failed");
}

UserContext user = UserContext.builder()
    .attributesJson("{\"id\":\"user-123\"}")
    .build();

boolean enabled = client.isOn("my-feature", user);

The plugin automatically sends feature usage and experiment view events, with the user’s attributes as context. The plugin doesn’t inherit the client’s SDK connection key, so pass it to both TrackingPluginConfig and Options.Keep one client for your application and create a separate tracking plugin for each client. At application shutdown, call client.shutdown() to flush pending events and release resources:

client.shutdown();

Custom events aren’t supported yet. Send them with the Ingestion API.

Option	Description
`ingestorHost`	Ingestor for your Data Region.
`batchSize`	Events to queue before sending. Default `100`.
`batchTimeout`	How long to wait before sending a partial batch. Default `Duration.ofSeconds(10)`.
`closeTimeout`	Time budget for flushing events during shutdown. Default `Duration.ofSeconds(5)`.

Requires the GrowthBook Kotlin SDK v7.8.0 or later, with NetworkDispatcherKtor v1.2.0+ or NetworkDispatcherOkHttp v1.1.0+.

import com.sdk.growthbook.GBSDKBuilder
import com.sdk.growthbook.network.GBNetworkDispatcherKtor
import com.sdk.growthbook.plugin.TrackingPluginConfig
import com.sdk.growthbook.plugin.tracking.GrowthBookTrackingPlugin

val networkDispatcher = GBNetworkDispatcherKtor()

val growthBook = GBSDKBuilder(
    apiKey = "YOUR_CLIENT_KEY",
    apiHost = "https://cdn.growthbook.io/",
    attributes = attributes,
    networkDispatcher = networkDispatcher,
    trackingCallback = { _, _ -> },
)
    .setPlugins(
        listOf(
            GrowthBookTrackingPlugin(
                TrackingPluginConfig(
                    clientKey = "YOUR_CLIENT_KEY",
                    networkDispatcher = networkDispatcher,
                    ingestorHost = "https://us-east-1.gb-ingest.com",
                )
            )
        )
    )
    .initialize()

The plugin doesn’t inherit the builder’s client key or network dispatcher, so pass both to TrackingPluginConfig. Without a network dispatcher, no events are sent.Custom events aren’t supported yet. Send them with the Ingestion API.

Option	Description
`ingestorHost`	Ingestor for your Data Region.
`batchSize`	Events to queue before sending. Default `100`.
`batchTimeout`	How long to wait before sending a partial batch. Default `10.seconds`.

Requires the GrowthBook Swift SDK v1.1.15 or later.

import GrowthBook

let gb: GrowthBookSDK = GrowthBookBuilder(
    apiHost: "https://cdn.growthbook.io",
    clientKey: "YOUR_CLIENT_KEY",
    attributes: ["id": "user-123"],
    trackingCallback: { _, _ in }
)
.addPlugin(GrowthBookTrackingPlugin(
    config: .init(ingestorHost: "https://us-east-1.gb-ingest.com")
))
.initializer()

Custom events aren’t supported yet. Send them with the Ingestion API.

Option	Description
`ingestorHost`	Ingestor for your Data Region.
`batchSize`	Events to queue before sending. Default `100`.
`batchTimeout`	Seconds to wait before sending a partial batch. Default `10`.

Sending events to the right region

The tracking plugin sends events to https://us-east-1.gb-ingest.com by default. If you selected eu-west-1 as your Event Forwarder’s Data Region, set the ingestor host option shown for your SDK above to https://eu-west-1.gb-ingest.com. Otherwise events won’t reach the proper ingestion server and your events will be dropped. You can find your Event Forwarder’s configured region on the data source’s Event Forwarder settings.

Ingestion API

You can also send events directly to our ingestion API. Pass an array of event objects, each with the following properties:

event_name: The name of the event (e.g., “Purchase”, “Button Click”)
properties: Optional key-value pairs with properties of the event itself
attributes: Optional key-value pairs with attributes of the user or context at the time of the event
YOUR_WAREHOUSE_REGION: either us-east-1 or eu-west-1 depending on what you selected when creating your datasource
YOUR_CLIENT_KEY: The key from your sdk connection. Go to https://app.growthbook.io/sdks/ click on your connection or make a new one. Copy the text from the “Client Key”

curl -X POST "https://YOUR_WAREHOUSE_REGION.gb-ingest.com/track?client_key=YOUR_CLIENT_KEY" \
-H "Content-Type: application/json" \
-d '[{
  "event_name": "Purchase",
  "properties": {
    "amount": 100
  },
  "attributes": {
    "user_id": "12345"
  }
}]'

Using the wrong host means events won’t reach the proper ingestion server and your events will be dropped.

Experiment View Events

In order to use GrowthBook’s experiment analysis features, you must send an event every time a user views an experiment. It must match the following format:

event_name: Must be "Experiment Viewed"
properties: Must include the following key/value pairs:
- experimentId: The ID of the experiment being viewed
- variationId: The ID of the variation that was shown to the user

In addition, you must include attributes with the user attributes that were used to evaluate the experiment, plus any attributes you want to use as dimensions for slicing and dicing.

Feature Usage Events

To take advantage of GrowthBook’s feature usage analytics, you must send an event every time a feature is evaluated with a specific format.

event_name: Must be "Feature Evaluated"
properties: Must include the following key/value pairs:
- feature: The name of the feature being evaluated
- value: The feature’s value that was returned from the evaluation
- source: (optional) The source of the feature value (e.g., “defaultValue”, “experiment”, “force”)
- ruleId: (optional) The ID of the specific rule that was used to evaluate the feature (or $default if the default value was used)
- variationId: (optional) If the value came from an experiment, the ID of the variation that was returned

Attributes

Attributes are key-value pairs that provide context about the user or environment at the time of the event. They can be used to slice and dice your data in analysis. It’s recommended to include the same attributes you use in your GrowthBook SDK. Some attributes are enriched in the ingestion API if provided:

ip - a geoip lookup is done and the following attributes are added. If an ip attribute is not provided, we will use the IP address of the request.
- geo_country
- geo_city
- geo_lat
- geo_lon
ua - the user agent is parsed and the following attributes are added. If a user agent attribute is not provided, we will use the user agent of the request.
- ua_browser (e.g. Safari)
- ua_os (e.g. macOS)
- ua_device_type (e.g. mobile)
url - the URL is parsed and the following attributes are added:
- url_path (e.g. /products/123)
- url_host (e.g. www.example.com)
- url_query (e.g. ?utm_source=google)
- url_fragment (e.g. #section1)

It’s also recommend to include attributes about which SDK is being used. This can help with debugging.

sdk_language (e.g. python)
sdk_version (e.g. 1.2.3)

Limits

When calling the ingestion API directly, please be aware of the following default limits:

Maximum of 100 events per request
Maximum of 1 request per second

These limits are to protect accidental misuse of the API. Our Ingestion API can handle much higher volumes than this. Reach out to your account manager if you need to increase your limits.

​Benefits

​How it Works

​Connection Permissions

​BigQuery

​Snowflake

​Databricks

​Before you start: is Zerobus available for your workspace?

​Finding your Zerobus endpoint

​Network Access

​Get Started

​Sending Events

​With SDKs

​Sending events to the right region

​Ingestion API

​Experiment View Events

​Feature Usage Events

​Attributes

​Limits

Benefits

How it Works

Connection Permissions

BigQuery

Snowflake

Databricks

Before you start: is Zerobus available for your workspace?

Finding your Zerobus endpoint

Network Access

Get Started

Sending Events

With SDKs

Sending events to the right region

Ingestion API

Experiment View Events

Feature Usage Events

Attributes

Limits