Firehose - Everflow API

Firehose is Everflow’s real-time event streaming service. Instead of polling the REST API for new data, Firehose pushes events to your infrastructure as they happen — with sub-second latency and no rate limiting.

When to use Firehose vs streaming vs export

Everflow gives you three ways to move data out of the platform at scale. Pick by use case:

	Firehose	Streaming endpoints (`/clicks/stream`, `/conversions/stream`)	Export endpoints (`/conversions/export`, etc.)
Delivery model	Pushed to you in real time	You pull, server streams the response	You pull, server returns a file (CSV/JSON)
Latency	Sub-second	Seconds, depending on volume	Minutes for large windows
Volume per request	Unbounded — every event flows continuously	Bounded by date range	Bounded by date range; capped by file size
Rate limits	None	Counts against the API rate limit	Counts against the API rate limit
Use when	You want a live event pipeline (warehouse, dashboards, automation)	You’re backfilling or pulling a fixed historical window	You need a downloadable file for ad-hoc analysis or third-party tools
Setup	Provisioned by Everflow Support — see below	Available out of the box	Available out of the box

If your goal is ongoing replication of clicks/conversions/events into your data warehouse, Firehose is the right pick. If you’re bootstrapping an integration or pulling a fixed historical window, the streaming endpoints are usually faster to wire up. Use exports when a human (or another tool) is going to consume the file directly.

Supported event types

Firehose can stream any combination of these event types:

Event type	Description
Clicks	Fired when a user clicks a tracking link. Includes device info, geolocation, query parameters, and attribution data.
Impressions	Fired when an impression pixel loads. Includes device and geolocation data. Requires the impression tracking package.
Conversions	Fired when a conversion event is recorded. Includes conversion details, payout/revenue, event names, and custom parameters.
Conversion updates	Fired when a conversion status changes (e.g., approved, rejected) or when payout/revenue values are modified.

Supported delivery platforms

Firehose supports the following delivery methods:

Amazon SQS

Events are delivered to an Amazon Simple Queue Service (SQS) queue. Supports both Standard and FIFO queue types.

Standard queues — Best-effort ordering, at-least-once delivery, maximum throughput
FIFO queues — Guaranteed ordering within message groups, exactly-once processing

You provide:

AWS Region
SQS Queue URL
IAM credentials or cross-account role ARN for Everflow to publish to your queue

Google Cloud Pub/Sub

Events are published to a Google Cloud Pub/Sub topic. Supports optional message attributes for custom routing. You provide:

Google Cloud Project ID
Pub/Sub Topic name
Service account credentials for Everflow to publish to your topic

HTTP/HTTPS POST

Events are delivered as JSON payloads via HTTP POST requests to your custom endpoint. You provide:

The URL to receive events
Any required authentication headers (e.g., API keys, bearer tokens)

Azure Event Hubs

Available on request. Contact Everflow Support to configure Azure Event Hubs delivery.

Event payloads

Each event is delivered as a JSON object. The payload structure is configurable — you can choose which fields to include and define custom field mappings.

Click payload example

{
  "transaction_id": "890c3d5ff4294bd08291e3a32e9a9a2e",
  "is_unique": true,
  "unix_timestamp": 1715788261,
  "network_id": 1,
  "network_offer_id": 1,
  "network_offer_group_id": 0,
  "network_campaign_id": 0,
  "network_affiliate_id": 1,
  "affiliate_manager_id": 1,
  "sales_manager_id": 0,
  "account_executive_id": 0,
  "network_advertiser_id": 13,
  "account_manager_id": 1,
  "network_offer_creative_id": 0,
  "category_id": 1,
  "tracking_url": "www.servetrack.test",
  "source_id": "",
  "sub1": "facebook",
  "sub2": "",
  "sub3": "",
  "sub4": "",
  "sub5": "",
  "sub6": "",
  "sub7": "",
  "sub8": "",
  "sub9": "",
  "sub10": "",
  "project_id": "",
  "payout": 0.0,
  "revenue": 0.0,
  "currency_id": "USD",
  "referer": "",
  "error_code": 0,
  "error_filter_id": "",
  "is_test_mode": false,
  "user_ip": "24.48.77.8",
  "http_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ...",
  "http_accept_language": "en-US,en;q=0.9",
  "query_parameters": {
    "sub1": "facebook",
    "some_parameter": "some-app"
  },
  "redirect_url": "http://everflowclient.io/test.php?aid=1&oid=1&tid=890c3d5ff4294bd08291e3a32e9a9a2e",
  "network_offer_url_id": 0,
  "is_view_through": false,
  "is_async": false,
  "country_code": "CA",
  "cost": 0.0,
  "session_id": "ac3cf6847fbb40ef953dc5f626790d44",
  "session_start": 1715788260,
  "coupon_code": "",
  "redirect_method": "standard",
  "is_sdk_click": false,
  "is_organic_click": false,
  "has_device_info": true,
  "has_geolocation": true,
  "geolocation": {
    "countryCode": "CA",
    "countryName": "Canada",
    "regionCode": "QC",
    "regionName": "Quebec",
    "cityName": "Montreal",
    "ispName": "videotron ltee",
    "dma": 0,
    "postalCode": "h2l 0a1",
    "timezone": "America/Montreal",
    "carrierName": "",
    "carrierCode": 0,
    "organization": "Videotron Ltee",
    "isMobile": false,
    "isProxy": false
  },
  "device_info": {
    "isMobile": false,
    "platformName": "macOS",
    "osVersion": "10.11",
    "brand": "Apple",
    "model": "Macintosh",
    "isTablet": false,
    "browserName": "Chrome",
    "browserVersion": "81",
    "deviceType": "PC",
    "language": "en",
    "httpAcceptLanguage": "en-US,en;q=0.9",
    "isRobot": false,
    "isFilter": false
  }
}

Impression payload example

{
  "transaction_id": "cf263009c5954d1585861a103066a41d",
  "unix_timestamp": 1715788332,
  "network_id": 1,
  "network_offer_id": 1,
  "network_affiliate_id": 1,
  "affiliate_manager_id": 1,
  "network_advertiser_id": 13,
  "account_manager_id": 1,
  "network_offer_creative_id": 0,
  "network_offer_url_id": 0,
  "category_id": 1,
  "tracking_url": "www.servetrack.test",
  "source_id": "",
  "sub1": "facebook",
  "sub2": "",
  "sub3": "",
  "sub4": "",
  "sub5": "",
  "sub6": "",
  "sub7": "",
  "sub8": "",
  "sub9": "",
  "sub10": "",
  "project_id": "",
  "payout": 0.0,
  "revenue": 0.0,
  "currency_id": "USD",
  "referer": "",
  "user_ip": "24.48.77.8",
  "http_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ...",
  "http_accept_language": "en-US,en;q=0.9",
  "query_parameters": {
    "sub1": "facebook",
    "some_parameter": "some-app"
  },
  "is_view_through": true,
  "is_async": false,
  "cost": 0.0,
  "network_tracking_domain_id": 1,
  "coupon_code": "",
  "is_sdk_impression": false,
  "has_device_info": true,
  "has_geolocation": true,
  "geolocation": {
    "countryCode": "CA",
    "countryName": "Canada",
    "regionCode": "QC",
    "regionName": "Quebec",
    "cityName": "Montreal",
    "ispName": "videotron ltee",
    "dma": 0,
    "postalCode": "h2l 0a1",
    "timezone": "America/Montreal",
    "carrierName": "",
    "carrierCode": 0,
    "organization": "Videotron Ltee",
    "isMobile": false,
    "isProxy": false
  },
  "device_info": {
    "isMobile": false,
    "platformName": "macOS",
    "osVersion": "10.11",
    "brand": "Apple",
    "model": "Macintosh",
    "isTablet": false,
    "browserName": "Chrome",
    "browserVersion": "81",
    "deviceType": "PC",
    "language": "en",
    "httpAcceptLanguage": "en-US,en;q=0.9",
    "isRobot": false,
    "isFilter": false
  }
}

Conversion payload example

{
  "conversion_id": "2e6d2c14125044c89a7b8da3d10d92e7",
  "transaction_id": "890c3d5ff4294bd08291e3a32e9a9a2e",
  "date": "2024-05-15 15:53:19",
  "click_date": "2024-05-15 15:51:01",
  "delta_hours": "0.04",
  "network_id": "1",
  "network_affiliate_id": "1",
  "network_offer_id": "1",
  "network_offer_group_id": "",
  "network_campaign_id": "",
  "affiliate_manager_id": "1",
  "network_advertiser_id": "13",
  "account_manager_id": "1",
  "network_offer_creative_id": "0",
  "category_id": "1",
  "source_id": "",
  "sub1": "facebook",
  "sub2": "",
  "sub3": "",
  "sub4": "",
  "sub5": "",
  "sub6": "",
  "sub7": "",
  "sub8": "",
  "sub9": "",
  "sub10": "",
  "adv1": "",
  "adv2": "",
  "adv3": "",
  "adv4": "",
  "adv5": "",
  "adv6": "",
  "adv7": "",
  "adv8": "",
  "adv9": "",
  "adv10": "",
  "session_user_ip": "24.48.77.8",
  "conversion_user_ip": "127.0.0.1",
  "http_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ...",
  "project_id": "",
  "payout_type": "PRV",
  "revenue_type": "RPA",
  "country": "Canada",
  "region": "Quebec",
  "city": "Montreal",
  "dma": "0",
  "carrier": "",
  "platform": "macOS",
  "os_version": "10.11",
  "device_type": "PC",
  "brand": "Apple",
  "browser": "Chrome",
  "language": "en",
  "conversion_status": "approved",
  "event_name": "",
  "payout": ".50",
  "revenue": "1.00",
  "is_view_through": "0",
  "coupon_code": "",
  "order_id": "",
  "error_code": "0",
  "sale_amount": ".00",
  "isp": "videotron ltee",
  "referer": "",
  "currency_id": "USD",
  "conversion_timestamp": 1715788399,
  "network_offer_url_id": "0",
  "query_parameters": {
    "transaction_id": "890c3d5ff4294bd08291e3a32e9a9a2e",
    "nid": "1",
    "arbitrary_parameter": "some-value"
  }
}

Conversion update payload example

The conversion update payload is identical to the conversion payload, with the addition of an update_timestamp field indicating when the update occurred.

{
  "conversion_id": "2e6d2c14125044c89a7b8da3d10d92e7",
  "transaction_id": "890c3d5ff4294bd08291e3a32e9a9a2e",
  "date": "2024-05-15 15:53:19",
  "click_date": "2024-05-15 15:51:01",
  "delta_hours": "0.04",
  "network_id": "1",
  "network_affiliate_id": "1",
  "network_offer_id": "1",
  "conversion_status": "approved",
  "payout": "1.25",
  "revenue": "2.00",
  "event_name": "",
  "sale_amount": ".00",
  "order_id": "",
  "currency_id": "USD",
  "conversion_timestamp": 1715788399,
  "update_timestamp": "1715788460",
  "query_parameters": {
    "transaction_id": "890c3d5ff4294bd08291e3a32e9a9a2e",
    "nid": "1",
    "arbitrary_parameter": "some-value"
  }
}

Payload configuration

When setting up your Firehose, you can customize:

Field selection — Choose which fields to include in each event type
Field mapping — Rename fields to match your data schema (e.g., rename affiliate_id to partner_id)
Raw query parameters — Optionally include the full raw query string from the tracking URL
Event filtering — Stream only specific event types (e.g., conversions only)

Setup

Firehose is configured by the Everflow team. To get started:

Choose your delivery platform — SQS, Pub/Sub, HTTP, or Azure
Provision your infrastructure — Create the queue, topic, or endpoint on your side
Contact Everflow Support — Provide your infrastructure details (queue URL, topic name, endpoint URL, and credentials)
Configure your payload — Work with the Everflow team to define which fields and event types to include
Start receiving events — Everflow enables the stream and events begin flowing in real time

Contact Support

Reach out to the Everflow Support team to set up Firehose for your account.

​When to use Firehose vs streaming vs export

​Supported event types

​Supported delivery platforms

​Amazon SQS

​Google Cloud Pub/Sub

​HTTP/HTTPS POST

​Azure Event Hubs

​Event payloads

​Click payload example

​Impression payload example

​Conversion payload example

​Conversion update payload example

​Payload configuration

​Setup