Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.everflow.io/llms.txt

Use this file to discover all available pages before exploring further.

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:
FirehoseStreaming endpoints (/clicks/stream, /conversions/stream)Export endpoints (/conversions/export, etc.)
Delivery modelPushed to you in real timeYou pull, server streams the responseYou pull, server returns a file (CSV/JSON)
LatencySub-secondSeconds, depending on volumeMinutes for large windows
Volume per requestUnbounded — every event flows continuouslyBounded by date rangeBounded by date range; capped by file size
Rate limitsNoneCounts against the API rate limitCounts against the API rate limit
Use whenYou want a live event pipeline (warehouse, dashboards, automation)You’re backfilling or pulling a fixed historical windowYou need a downloadable file for ad-hoc analysis or third-party tools
SetupProvisioned by Everflow Support — see belowAvailable out of the boxAvailable 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 typeDescription
ClicksFired when a user clicks a tracking link. Includes device info, geolocation, query parameters, and attribution data.
ImpressionsFired when an impression pixel loads. Includes device and geolocation data. Requires the impression tracking package.
ConversionsFired when a conversion event is recorded. Includes conversion details, payout/revenue, event names, and custom parameters.
Conversion updatesFired 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": "",
  "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": "",
  "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": "",
  "adv1": "",
  "adv2": "",
  "adv3": "",
  "adv4": "",
  "adv5": "",
  "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:
  1. Choose your delivery platform — SQS, Pub/Sub, HTTP, or Azure
  2. Provision your infrastructure — Create the queue, topic, or endpoint on your side
  3. Contact Everflow Support — Provide your infrastructure details (queue URL, topic name, endpoint URL, and credentials)
  4. Configure your payload — Work with the Everflow team to define which fields and event types to include
  5. 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.