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.1"- Payload schema identifier:
webhook_outbound_payload_v1 - JSON field names are
snake_case. request_idis a webhook dispatch/log correlation UUID. It is not a hit, conversion, or custom-event ID.session,url_buffer,is_action,action_number, andaction_dataare 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.1". "1.1" added the always-present referring_page_id and referring_page_name fields; "1.0" payloads were sent before them. |
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. |
referring_page_id | string | always sent | ID of the most recent page in the current journey before the current step, or before the converting page hit for conversion_triggered and custom_event_triggered. Non-page steps are skipped. Empty string when no earlier page exists. |
referring_page_name | string | always sent | Name of that earlier page. Empty string when there is no earlier page or its name cannot be loaded; a known referring_page_id is still sent. |
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. |
referring_page_id and referring_page_name are top-level JSON payload fields and are always present, including when no session object exists. An on_action webhook resolves them from the action step, so the page the visitor clicked on counts as the earlier page. A conversion or custom-event webhook resolves them from its converting page hit, so the same click can produce a different referring page. A fresh entrance does not inherit a page from an earlier journey.
FunnelFlux sends both fields on every webhook from the release that contains runtime change 01a85a4df. Payloads delivered before that release do not have them. Payloads that carry them say schema_version "1.1". The v1 JSON Schema requires both fields when schema_version is "1.1" and keeps them optional for "1.0", so stored 1.0 payloads from earlier deliveries stay valid.
These are payload fields, not URL tokens. Webhook destination URLs are not token-substituted, and these fields do not change that.
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 accumulated URL/action params 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
funnel
Available keys:
Code
traffic_source
Available keys:
Code
hit
Available keys:
Code
session
Available keys:
Code
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-urlencodedmultipart/form-datatext/plainkey-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. |
is_action and action_number are intentionally top-level fields and are not duplicated inside action_data.
conversion
Available keys:
Code
custom_event
Available keys:
Code
Example: In-Flow Webhook Node
Code
Example: Conversion Webhook
Code
Example: Custom Event Webhook
Code
Field Semantics
request_ididentifies 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_idis the normalized tracking hit associated with the webhook event when available.funnel.node_idis the current or event-associated funnel node when available.session.most_recent_page_idis Edge page context, not the current webhook node. It can be the current hit's own page, so it is not a referring page. Use top-levelreferring_page_idfor the page strictly before the current step.tracking_fieldsare entrance attribution values.url_bufferis the current Edge token buffer.action_datais request-submitted action data and action-origin metadata for in-flow executions.conversionandcustom_eventare 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.
FunnelFlux no longer adds origin_page_id or origin_page_name to action_data. Use the top-level referring_page_id and referring_page_name fields instead. Action parameters that the visitor's request submits are still passed through as customer data, even when their names match these keys.