Streams
Streams, formerly referred to as Behavioral Webhooks, send real-time behavioral data to an external system, like an HTTP webhook endpoint. Streams can be configured to trigger after a single event or after multiple events (Event Pattern) are observed within a specified time period.
Setting up Streams
Streams are configured within the Fullstory application. See the Streams Help Doc for setup guidance.
Activation Quota
Triggers from Streams are metered through a usage-based metric called "Activations". See Activation Quota to learn more.
| Method | Consumption Rate |
|---|---|
| Streams (Single Event) | 1⁄100th Activation per trigger |
| Streams (Event Patterns) | 1 Activation per trigger |
Sync Expectations
Streams are triggered when a single event or event pattern matches a stream definition. Note the timestamp value
which can be sent to the downstream destination with Field Mapping.
There will be some observed latency between an event occurring and Fullstory sending an HTTP request to your stream endpoint. This latency will vary based on processing time and other factors including when each event is reported to Fullstory. For example, in disconnected client scenarios Fullstory may be notified about an event minutes or even hours after the event occurred.
Customizable Payload
With Streams, the request body sent to your destination is fully customizable. Instead of a predefined schema, you use the Field Mapping interface to construct a JSON payload that matches the exact requirements of your endpoint. This allows for seamless integration with a wide variety of third-party tools.
In your Stream configuration, the Field Mapping section allows you to define key-value pairs for the payload. For each row, you select a Fullstory data point as the Event property and specify the key it should be assigned to in the outgoing JSON as the Destination field.
The following tables detail the properties available to be mapped into your custom payload in the Field Mapping interface.
Event
| Event property | Destination field | Description |
|---|---|---|
| Timestamp | event_time | The UTC timestamp when the event occurred. |
| Event Type | event_type | The type of event, such as Click, Change, or a Custom Event name. |
| Source Type | source_type | Where the event originated from, such as Web, Mobile, or API. |
| App URL | app_url_event | The Fullstory Session Replay URL that seeks to the specific event. |
| Target Text | target_text | The text content of the element associated with the event (e.g., button text). |
| Element Name | element_name | The name that identifies the element associated with the event. |
Event Properties (optional)
| Event property | Description |
|---|---|
| (Custom) | Your custom key-value pairs sent with events via the FS(‘trackEvent’) API. e.g., revenue |
Element Properties (optional)
| Event property | Description |
|---|---|
| (Custom) | Custom properties extracted from elements during an event. e.g., product_sku |
Page
| Event property | Destination field | Description |
|---|---|---|
| URL | url | The full URL of the page view. |
| Initial Referrer | referer_url | The referrer for the first page view of the session. |
| Name | page_name | The name of the page as defined via the FS('setProperties', { type: 'page' }) API. |
Page Properties (optional)
| Event property | Description |
|---|---|
| (Custom) | Your custom key-value pairs associated with a page via the FS('setProperties', { type: 'page' }) API. e.g., page_category |
Session
| Event property | Destination field | Description |
|---|---|---|
| Session ID | session_id | Fullstory's unique identifier for the session. |
| Client ID | client_session_id | Fullstory's unique client identifier. In other Fullstory APIs, this value is the full "session ID", and is formatted as {guid:guid} representing the {device_id:session_id} pair. |
| Session UID | session_uid | A custom session identifier, if provided via API. |
| Browser | ua_browser | The name of the user's browser (e.g., Chrome, Safari). |
| Browser Version | ua_browser_version | The version of the user's browser. |
| Device | ua_device | The type of device used (e.g., Desktop, Tablet, Mobile). |
| User Agent Operating System | ua_operating_system | The operating system parsed from the user agent string. |
| IP Address | ip_address | The IP address associated with the session. |
| Country | country | The country associated with the session's IP address. |
| Region | region | The region or state associated with the session's IP address. |
| City | city | The city associated with the session's IP address. |
| Device Manufacturer | device_manufacturer | The manufacturer of the mobile device. e.g. Apple, Samsung |
| Device Model | device_model | The model of the mobile device. e.g. iPhone12,5, Pixel 5 |
| Device Operating System | device_operating_system | The operating system of the mobile device (e.g., iOS). |
| Device Operating System Version | device_os_version | The version of the mobile device's operating system. |
| App Screen Name | app_screen_name | The name of the current screen in a mobile application. |
| Build Variant | app_build_variant | The build variant of the mobile application. |
| App ID | app_id | The bundle identifier or application ID of the mobile app. |
| App Name | app_name | The name of the mobile application. |
| App Version | app_version | The version of the mobile application. |
| App URL | app_url_session | The Fullstory Session Replay URL. |
User
| Event property | Destination field | Description |
|---|---|---|
| Device ID | device_id | The Device ID indicates a unique capture device for the event. For web capture, the ID corresponds to a unique user cookie. For mobile capture, this corresponds to a single app/device combo. |
| User ID | user_id | The unique ID for the user provided through the API. |
user_email | The email address for the user as provided through the API. | |
| Display Name | user_display_name | The user's display name, if identified. |
| App URL | app_url_user | The URL of the user details in Fullstory. |
User Properties (optional)
| Event property | Description |
|---|---|
| (Custom) | Your custom key-value pairs associated with a user via the FS('setProperties', { type: 'user' }) API. e.g., subscription_tier |
Advanced JSON Mapping
For complex payload structures that may require nesting or specific data types, you can switch from the "Fields" view to the "JSON" view. This provides a raw JSON editor for maximum flexibility.
Note: Once you save a mapping using the raw JSON editor, you may not be able to switch back to the simplified "Fields" UI for that Stream. If you need to switch back, you can clear the JSON and start fresh with new Fields.
Delivery Guarantees
Fullstory attempts to send each matching event to a stream only once. However, there are rare cases where an event may be sent multiple times to a stream.
If the response from your receiving endpoint indicates the event wasn't successfully processed, Fullstory will retry sending an event up to 30 times over a 5 hour period following the initial attempt.
Fullstory will retry sending an event if any of the following are true:
- The request to the receiving endpoint times out (Fullstory does not receive a response from your endpoint within 5 seconds).
- There's a general network error communicating with the receiving endpoint (e.g. connection closed).
- The response HTTP status code is between
500and599. - The response HTTP status code is
302,303,307, or429.
Fullstory will not retry sending an event if any of the following are true:
- The receiving endpoint IP address is not resolved to a public IP address.
- There's an issue with the overall stream configuration (e.g. an invalid URL is specified).
- The stream begins to experiences a high rate of failures of significant volume.
- The response HTTP status code is any code not specified in retryable criteria above.
Rate Limits
Fullstory does not rate limit outbound streams. While multi-event patterns are matched as once per session, single event streams can optionally be configured to match as once per event. At minimum, your receiving endpoint should be prepared to handle a ceiling of your total session capture rate. If your Fullstory account captures 50 sessions per second, your receiving endpoint could receive 50 requests per second if every session matched your stream definition. Adjust receiving endpoint capacity accordingly to account for multiple streams per session and/or if you expect a burst in traffic that matches the stream definition.
IP Addresses
Fullstory will send stream requests from the following IP addresses.
US Region
8.35.195.0/29
EU Region
34.89.210.80/29