Webhook Payload Format
Basic Structure
json
1{
2 "email": "lead@example.com",
3 "event": "event_name",
4 "properties": {
5 "key": "value"
6 }
7}Field Reference
No single field is strictly required for the webhook to accept a payload. However, for a signal to be processed into a lead, at least one persistent identifier must be present.
Identifying Fields
At least one of these should be present for the signal to create or match a lead:
| Field | Type | Description |
|---|---|---|
| string | Lead's email address. Primary identifier for matching signals to leads. Case-insensitive. Can appear at top level, in traits, properties, or context.traits | |
| userId | string | Your internal user identifier (product user ID) |
| anonymousId | string | Anonymous visitor identifier (for identity resolution). Not sufficient alone to create a lead, but enables cold storage rehydration when later identified |
Recommended
| Field | Type | Description |
|---|---|---|
| event | string | Event name (e.g., form_submission, page_view, demo_request) |
| type | string | Segment event type (track, page, identify). Used for source auto-detection |
| properties | object | Event-specific data |
Optional
| Field | Type | Description |
|---|---|---|
| timestamp | string | ISO 8601 timestamp (e.g., 2024-01-15T14:30:00Z). Defaults to receipt time if omitted |
| source | string | System that generated the signal (overrides auto-detection) |
| traits | object | User traits (common in Segment identify calls) |
| context | object | Contextual metadata (page info, device, etc.) |
Payload Examples
Form Submission
json
1{
2 "email": "prospect@company.com",
3 "event": "form_submission",
4 "timestamp": "2024-01-15T11:15:00Z",
5 "properties": {
6 "form_name": "Request Demo",
7 "form_id": "demo-form-main",
8 "page_url": "https://yoursite.com/demo",
9 "company": "TechCorp",
10 "company_size": "100-500",
11 "job_title": "Marketing Director"
12 }
13}Page View
json
1{
2 "email": "visitor@example.com",
3 "event": "page_view",
4 "properties": {
5 "page_url": "https://yoursite.com/pricing",
6 "page_title": "Pricing - Your Product",
7 "referrer": "https://google.com",
8 "time_on_page": 45
9 }
10}Product Trial Signup
json
1{
2 "email": "newuser@startup.io",
3 "event": "trial_started",
4 "properties": {
5 "plan": "pro_trial",
6 "trial_length_days": 14,
7 "signup_source": "website",
8 "company": "StartupIO"
9 }
10}How Properties Map to Signal Rules
Signal mapping rules can access any field using dot notation:
| Example Condition | Matches |
|---|---|
event equals demo_request | Signals with event "demo_request" |
properties.company_size equals Enterprise | Enterprise company signals |
properties.page_url contains /pricing | Pricing page activity |
Design your payload structure with your signal mapping rules in mind. Consistent field names across sources simplify rule creation.
Validation
| Rule | Requirement |
|---|---|
| JSON | Valid JSON syntax |
| Content-Type | Must be application/json |
| Encoding | UTF-8 |
The universal webhook is lenient with payload structure. If payload standardization fails, the raw payload is stored as-is with event type defaulting to the type or event field, or "universal" if neither is present.