Overview

Required plan

This feature or setting is available to all customers on any Recurly Engage subscription plan.

Prerequisites & limitations

You must have Company or App Administrator permissions in Recurly Engage.
add additional prerequisites or limitations if any

Definition

The Event API Firehose feature pushes usage tracking events in JSON format to external systems—either by writing to an S3 bucket or by POSTing to a custom web API endpoint—enabling real-time or batch consumption of event data.

Key benefits

Real-time insights: Stream usage events as they occur for immediate data-driven decisions.
Scalable storage: Offload event logs to S3 for long-term retention and BI integration.
Flexible integration: Send data to any HTTP endpoint or cloud storage service to fit your architecture.

Key details

S3 Event Data Logs

Usage tracking data that has been enabled in Recurly Engage can be pushed to external systems. Anything added in the Usage Tracker section is sent as an event once the integration is set up.

There are two ways to receive usage data. You must provide the following values to your account manager:

AWS S3 Requirements – Pull data using Recurly Engage:

Go to Settings→User Traits.

Select “Click here for AWS S3 credentials”.

Copy the AWS Bucket, Access Key, and Secret Key, then navigate to the exports folder. All filenames start with the usages prefix. Pull this data on demand.

AWS S3 data specifications

All data is JSON formatted with the following fields. To enable optional fields, ask your account manager:

Field	Description	Notes
user_id	Primary user identifier
anonymous_user_id	Identifier when userId is unavailable
event	Name of event
platform	Type of integration	Always `redfast` for usage
type	Type of tracker	Values: `page`, `track`, `custom`
properties.id	Usage Tracker id
properties.values	Configured values in Recurly Engage Console
properties.options	Additional options	Specifies if regex is used for page trackers
ts	Timestamp when activity occurred (epoch)
app_id	Recurly Engage app id	Optional
traits	Key/value pairs of user attributes ingested from external and in-app sources	Optional
segments	List of segment objects (id + name) at event time	Optional
paths	List of personalization path objects (id, name, device_type, zone)	Optional

Event types

Type	Description
Impression	User was shown the prompt
Timeout	User did not respond before timer expired
Dismiss	User dismissed by clicking `X` or outside the window
Decline	User clicked on the decline link
Click	User accepted the prompt (phased out in favor of Goal)
Goal	User accepted the prompt
Custom_Goals_[Activity Type]	User completed a defined custom goal on a prompt
Exclude	User excluded due to holdout or user limits
Holdout	User in holdout group
Pipeline_Impression	User shown the prompt and is in a pipeline stage
Pipeline_Transition	User moved from one pipeline stage to another

Custom Web API Firehose

This option provides near-real-time delivery. Recurly Engage can send single or batched events within sub-minute windows to an endpoint you specify. Provide your account manager with:

URL
API Key / Access Token
Request type (GET, POST, PUT)

Payload format

The payload is a JSON array of event objects. In S3 each event is one object per row.

[  
  { /* event object as shown below */ },  
  { /* ... */ }  
]

Example event payload

{
  "app_id": "74f72649-0327-4911-bd21-a4cd533cec1c",
  "user_id": "123",
  "anonymous_user_id": "2528a84d8fa8…",
  "event": "Home Page",
  "platform": "redfast",
  "type": "page",
  "ts": 1630476856,
  "properties": {
    "id": "8e282c72-07da-4c2f-bf91-85df633828af",
    "values": [{ "url_hash": "", "url_path": "/", "query_params": "" }],
    "options": { "use_regex": false }
  },
  "traits": { /* user trait key/value pairs */ },
  "segments": [{ "id": "...", "name": "Engaged" }, /* ... */],
  "paths": [{ "id": "...", "name": "Prompt A", "device_type": "web", "zone": "banner" }, /* ... */]
}

API data specifications

Field	Description	Notes
app_id	Recurly Engage app id
user_id	Primary user identifier
anonymous_user_id	Identifier when userId is unavailable
event	Name of event
platform	Always `redfast`
type	`page`, `track`, or `custom`
properties.id	Usage Tracker id
properties.values	Configured tracker values
properties.options	Regex or other options
ts	Epoch timestamp
traits	User attributes (key/value pairs)	Optional
segments	Segment list (id + name)	Optional
paths	Personalization path list (id, name, device_type, zone)	Optional

Usage types

Type	Description
page	Page view tracker
track	Button or CSS class click
custom	Custom event (e.g., transaction complete)

API Push example

curl 'example.backendurl.com/v1/api/ingest/' \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'your-api-key: abcdef' \
  --data-raw '[ { /* event objects */ } ]'