Copy page

Getting Started

Webhook Payloads

This page describes outbound webhook payloads sent by FunnelFlux Pro when a configured webhook fires.

Use this page when you are receiving webhook requests and need to validate, parse, store, or review the payload. It covers the public payload shape, field meanings, delivery headers, and examples for programming and AI-assisted integration review.

This is not the funnel asset schema for configuring webhook nodes inside a funnel. To create or update funnel nodes, see Creating Funnels and the Assets API funnel schema.

Scope

Outbound webhooks use one public payload contract for all FunnelFlux webhook trigger types.

• schema_version: "1.0"
• Payload schema identifier: webhook_outbound_payload_v1
• JSON field names are snake_case.
• request_id is a webhook dispatch/log correlation UUID. It is not a hit, conversion, or custom-event ID.
• session, url_buffer, is_action, action_number, and action_data are Edge-only fields and are present only for in-flow executions.
• Streamer-triggered conversion and custom-event webhooks do not synthesize Edge live-session state.

Machine-readable JSON Schema is available at webhook-outbound-payload-v1.schema.json.

Delivery Headers

FunnelFlux sends webhook requests with these headers:

Header	Value
X-Funnelflux-Payload-Schema	webhook_outbound_payload_v1
X-Funnelflux-Trigger-Type	Same value as body event_type.
X-Funnelflux-Request-ID	Same value as body request_id.

The payload schema header identifies this contract family. The body schema_version identifies the public body version inside that family.

Trigger Types

event_type	When it fires
node_execution	Visitor reaches a webhook node.
on_action	Visitor follows an action link or submits an action form with webhook bindings.
conversion_triggered	A conversion is processed for a traffic source with conversion webhook bindings.
custom_event_triggered	A custom event is processed for a traffic source with custom-event webhook bindings.

These event types use the same payload contract family. Use event_type to branch your integration logic when you need different handling by trigger source.

Common Fields

Field	Type	Required	Description
schema_version	string	yes	Current value is "1.0".
event_type	string	yes	One of the four trigger types above.
request_id	string	yes	Unique webhook dispatch/log correlation UUID.
timestamp	integer	yes	UTC Unix timestamp in milliseconds when the payload was built.
visitor	object	when available	Visitor, request, geo, and device context.
funnel	object	when available	Funnel and current-node context.
traffic_source	object	when available	Traffic source context.
hit	object	when available	Normalized hit context.
tracking_fields	object	when available	Entrance tracking fields captured from the traffic source URL.
visitor_tags	array	when available	Visitor tag IDs captured at event time; falls back to hit tags when event tags are unavailable.

Edge In-Flow Fields

These fields are present only for in-flow executions such as node_execution and on_action.

Field	Type	Description
session	object	Edge live-session and current-hit identifiers.
url_buffer	object	Current URL buffer / AccuBuffer values available for token replacement.
is_action	boolean	Whether this execution was caused by an action link or form submit.
action_number	integer	Action number when is_action is true.
action_data	object	Non-system action query/body values plus action origin metadata. Empty object when no action data exists.

Conversion and custom-event webhooks are triggered after analytics processing. They do not include Edge live-session fields.

Event Extensions

Field	Type	Description
conversion	object	Present for conversion_triggered. Contains normalized conversion data, including conversion_id.
custom_event	object	Present for custom_event_triggered. Contains normalized custom-event data, including custom_event_id.

Object Fields

visitor

Available keys:

Code
visitor_id
ip
user_agent
country_code
country_name
region
city
timezone
language
device_type
os
browser
connection_type

funnel

Available keys:

Code
funnel_id
funnel_name
node_id
node_name

traffic_source

Available keys:

Code
traffic_source_id
name

hit

Available keys:

Code
hit_id
hit_timestamp
tracking_domain
entrance_id
entrance_timestamp
is_new_visitor
is_entrance
is_unique_node_view
visitor_id
traffic_source_id
funnel_id
node_id
page_id
page_group_id
node_type
nodes_path
time_on_page
referrer
filtered_traffic
tracking_fields

session

Available keys:

Code
visitor_id
hit_id
entrance_id
entrance_timestamp
hit_timestamp
reference_hit_id
most_recent_page_id
referrer

action_data

action_data contains non-system action query/body values plus action origin metadata. Values may be strings, numbers, booleans, or null.

For action form submits and POST requests, supported parsed inputs include:

• URL query parameters
• application/x-www-form-urlencoded
• multipart/form-data
• text/plain key-value lines
• raw JSON object bodies

System routing keys such as FunnelFlux action/session routing parameters are omitted.

Common origin metadata keys include:

Field	Type	Description
origin_node_id	string	Node ID that originated the action.
origin_node_name	string	Origin node name.
origin_node_type	string	Origin node type, such as landerGroup or offerGroup.
origin_page_id	string	Resolved origin page ID when the action came from a page/group node.
origin_page_name	string	Resolved origin page name when available.

is_action and action_number are intentionally top-level fields and are not duplicated inside action_data.

conversion

Available keys:

Code
conversion_id
hit_id
transaction
revenue
conversion_timestamp
conversion_time
event_data1
event_data2
pii_email
pii_phone
passthrough_params

custom_event

Available keys:

Code
custom_event_id
event_number
hit_id
revenue
timestamp
conversion_time
event_data1
event_data2
pii_email
pii_phone
passthrough_params

Example: In-Flow Webhook Node

Code
{
  "schema_version": "1.0",
  "event_type": "node_execution",
  "request_id": "afa7f540-76d9-4bfe-a18d-4bc4d690ea56",
  "is_action": true,
  "action_number": 1,
  "timestamp": 1780062493221,
  "visitor": {
    "visitor_id": "visitor_123",
    "ip": "203.0.113.42",
    "user_agent": "Mozilla/5.0",
    "language": "en-US"
  },
  "funnel": {
    "funnel_id": "funnel_123",
    "funnel_name": "Webhook Action Test",
    "node_id": "node_webhook",
    "node_name": "Webhook"
  },
  "traffic_source": {
    "traffic_source_id": "ts_123",
    "name": "7SearchPPC Test"
  },
  "hit": {
    "hit_id": "hit_123",
    "hit_timestamp": 1780062493202,
    "visitor_id": "visitor_123",
    "traffic_source_id": "ts_123",
    "funnel_id": "funnel_123",
    "node_id": "node_webhook",
    "node_type": "webhook"
  },
  "session": {
    "visitor_id": "visitor_123",
    "hit_id": "hit_123",
    "entrance_id": "entrance_123",
    "entrance_timestamp": 1780062493000,
    "hit_timestamp": 1780062493202,
    "most_recent_page_id": "page_123"
  },
  "tracking_fields": {
    "campaign": "spring_sale",
    "external": "click-123"
  },
  "url_buffer": {
    "campaign": "spring_sale",
    "email": "alice@example.com"
  },
  "action_data": {
    "email": "alice@example.com",
    "origin_node_id": "node_lander",
    "origin_page_id": "page_123"
  },
  "visitor_tags": [
    "tag_abc123"
  ]
}

Example: Conversion Webhook

Code
{
  "schema_version": "1.0",
  "event_type": "conversion_triggered",
  "request_id": "0f28c95f-a519-49af-879d-94fbe6650f1d",
  "timestamp": 1780062500123,
  "visitor": {
    "visitor_id": "visitor_123",
    "ip": "203.0.113.42",
    "user_agent": "Mozilla/5.0"
  },
  "funnel": {
    "funnel_id": "funnel_123",
    "node_id": "node_offer"
  },
  "traffic_source": {
    "traffic_source_id": "ts_123",
    "name": "7SearchPPC Test"
  },
  "hit": {
    "hit_id": "hit_123",
    "hit_timestamp": 1780062493202,
    "visitor_id": "visitor_123",
    "traffic_source_id": "ts_123",
    "funnel_id": "funnel_123",
    "node_id": "node_offer",
    "node_type": "offer"
  },
  "tracking_fields": {
    "campaign": "spring_sale"
  },
  "visitor_tags": [
    "tag_abc123"
  ],
  "conversion": {
    "conversion_id": "conv_123",
    "hit_id": "hit_123",
    "transaction": "order_123",
    "revenue": "19.99",
    "conversion_timestamp": 1780062500000
  }
}

Example: Custom Event Webhook

Code
{
  "schema_version": "1.0",
  "event_type": "custom_event_triggered",
  "request_id": "8c42ff98-c7d8-45f2-98d8-e3e5dcfb1c73",
  "timestamp": 1780062501123,
  "visitor": {
    "visitor_id": "visitor_123",
    "ip": "203.0.113.42",
    "user_agent": "Mozilla/5.0"
  },
  "funnel": {
    "funnel_id": "funnel_123",
    "node_id": "node_offer"
  },
  "traffic_source": {
    "traffic_source_id": "ts_123",
    "name": "7SearchPPC Test"
  },
  "hit": {
    "hit_id": "hit_123",
    "hit_timestamp": 1780062493202,
    "visitor_id": "visitor_123",
    "traffic_source_id": "ts_123",
    "funnel_id": "funnel_123",
    "node_id": "node_offer",
    "node_type": "offer"
  },
  "tracking_fields": {
    "campaign": "spring_sale"
  },
  "visitor_tags": [
    "tag_abc123"
  ],
  "custom_event": {
    "custom_event_id": "hit_123_1",
    "event_number": 1,
    "hit_id": "hit_123",
    "revenue": "4.50",
    "timestamp": 1780062501000
  }
}

Field Semantics

• request_id identifies one webhook dispatch path and is the value stored in webhook logs/reporting. Do not treat it as a visitor ID, hit ID, conversion ID, or custom-event ID.
• hit.hit_id is the normalized tracking hit associated with the webhook event when available.
• funnel.node_id is the current or event-associated funnel node when available.
• session.most_recent_page_id is Edge page context, not the current webhook node.
• tracking_fields are entrance attribution values.
• url_buffer is the current Edge token buffer.
• action_data is request-submitted action data and action-origin metadata for in-flow executions.
• conversion and custom_event are event-specific extensions for streamer-triggered webhooks.
• Missing optional objects mean the context was not available for that execution.

Removed Legacy/Internal Fields

The public contract does not expose ref_hit or raw model keys such as HitID, ConversionID, and EventNumber. Use normalized hit, visitor, funnel, traffic_source, tracking_fields, conversion, and custom_event fields instead.