Skip to Content
StreamsForwarding

Event Forwarding

Route events in real-time to downstream analytics, marketing, and warehouse destinations. Each forwarding rule is scoped to a specific event source, so events from different apps can flow to different destinations without stepping on each other.

Overview

Event forwarding applies rules as events arrive. A rule matches when the event’s originating event source matches the rule’s configured source, and all of the rule’s filters and consent requirements are satisfied. Matching events are transformed (optionally), field-mapped, and delivered to the target destination.

Source-scoped event routing: events from different sources flow through the Forwarder which matches rules by source and writes to per-source destinations and warehouse tables

Creating a Forwarding Rule

  1. Navigate to Streams > Forwarding
  2. Click Create Forwarding Rule
  3. Give the rule a name
  4. Select an event source — the rule only fires for events arriving on this source’s write key
  5. Choose a target — an HTTP/CAPI destination or a warehouse source
  6. Configure event filters:
    • All events — Forward everything matching the source
    • Specific events — Select event types or names to forward
    • Condition-based — Forward events matching property conditions
  7. (Optional) Attach a JavaScript transformation
  8. Choose required consent categories
  9. Map event properties to destination fields
  10. Click Save

Why source scoping matters

Before source scoping, every forwarding rule applied to every event in the workspace — there was no way to route production events to one destination and development events to another, and no way to tell which app an event came from once it landed in a destination.

With source scoping you can:

  • Isolate environments — production and development write keys forward to different destinations
  • Route by app — a single workspace can run separate rule sets for Web, iOS, and Android sources
  • Scope per partner — give each integration partner a dedicated write key and a rule set they can’t interfere with
  • Trace provenance — every event carries write_key_id end-to-end, so you can always identify the source

Configuration

FieldTypeRequiredDescription
namestringYesRule name
event_key_idstringYesThe event source this rule applies to
destination_idstringConditionalTarget destination (HTTP/CAPI). Exactly one of destination_id or source_id must be set.
source_idstringConditionalTarget warehouse source for event persistence
event_filterobjectNoWhich events to forward (event types, event names, or condition tree)
transformation_idstringNoOptional reference to a JavaScript transformation
field_mappingarrayNoProperty name and path remappings
consent_categoriesarrayNoRequired consent categories (e.g., ["analytics", "marketing"])
configobjectNoPer-rule overrides: schema_name, custom_table_name, partition_column, staging_bucket
rate_limit_per_secintegerNoCap on events forwarded per second
statusstringYesdraft, active, paused, or error

When consent_categories is set, the forwarder checks the event’s context.consent before delivery. The event must have a true value for every required category; otherwise it is silently dropped (no delivery, no retry).

{
  "context": {
    "consent": {
      "analytics": true,
      "marketing": false,
      "advertising": false,
      "functional": true
    }
  }
}

An event with analytics: true but marketing: false will pass a rule requiring ["analytics"] but be dropped by a rule requiring ["analytics", "marketing"].

Delivery Monitoring

View delivery status for each forwarding rule:

  1. Open the forwarding rule detail page
  2. Check the Deliveries tab
  3. See success/failure counts, latency, and error details

Retry Logic

Failed deliveries are retried automatically:

  • 5 retry attempts with exponential backoff (1s → 2s → 4s → 8s → 16s, capped at 30s)
  • Dead letter queue for events that fail all retries
  • Retries on 5xx and 429 responses; fails fast on other 4xx

Warehouse Forwarding

When the target is a warehouse source (BigQuery, Snowflake, Databricks), events are batched, serialized to Avro, staged in Google Cloud Storage, and bulk-loaded into per-event-type tables. See Events warehouse for table naming, partitioning, and consent column details.

API Reference

See Events API for endpoint details.

Next Steps

Last updated on
TransformationsConsent Management