# 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](/creating-funnels) and the [Assets API funnel schema](/api/assets).

## 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](/schemas/webhooks/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:

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

### `funnel`

Available keys:

```text
funnel_id
funnel_name
node_id
node_name
```

### `traffic_source`

Available keys:

```text
traffic_source_id
name
```

### `hit`

Available keys:

```text
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:

```text
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:

```text
conversion_id
hit_id
transaction
revenue
conversion_timestamp
conversion_time
event_data1
event_data2
pii_email
pii_phone
passthrough_params
```

### `custom_event`

Available keys:

```text
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

```json
{
  "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

```json
{
  "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

```json
{
  "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.