Webhook Payload Formats

When a lead is captured, LeadCapture sends a POST request to your webhook endpoint containing all form data and system metadata. This article explains the full payload structure, system fields, and how each format looks so you can properly receive and parse lead data on your end.

Payload Contents

Every webhook payload includes two categories of data:

Form fields: All values the lead entered (name, email, phone, selections, etc.)
System fields: Metadata automatically captured by LeadCapture (IP address, page URL, verification status, etc.)

JSON Format (Default)

JSON is the most common format and is compatible with the majority of CRMs and APIs. The Content-Type header is set to application/json.

{
  "lead_id": "550e8400-e29b-41d4-a716-446655440000",
  "parent_url": "https://example.com/landing-page",
  "ip_address": "192.168.1.1",
  "user_agent": "Mozilla/5.0...",
  "is_partial_lead": false,
  "partial_lead_fields": [],
  "completed_steps": ["step-1", "step-2", "step-3"],
  "form_progress": 100,
  "first_name": "John",
  "last_name": "Doe",
  "email": "john@example.com",
  "phone": "+15551234567",
  "state": "California",
  "date_of_birth": "1990-01-15"
}

Form Data Format

Form Data uses application/x-www-form-urlencoded encoding. Field values are URL-encoded and joined with ampersands. This format is useful for simple HTTP endpoints and some lead distribution systems.

lead_id=550e8400-e29b-41d4-a716-446655440000&first_name=John&last_name=Doe&email=john%40example.com&phone=%2B15551234567

XML Format

XML wraps each field in its own element inside a root <lead> tag. The Content-Type header is set to application/xml.

<?xml version="1.0" encoding="UTF-8"?>
<lead>
  <lead_id>550e8400-e29b-41d4-a716-446655440000</lead_id>
  <first_name>John</first_name>
  <last_name>Doe</last_name>
  <email>john@example.com</email>
  <phone>+15551234567</phone>
</lead>

System Fields Reference

These fields are automatically included in every webhook payload. You can customize the field names per webhook using the Field Mapping section.

Default Field Name	Description
`lead_id`	Unique identifier for this lead
`parent_url`	URL of the page where the funnel was embedded or displayed
`ip_address`	Visitor's IP address
`user_agent`	Browser and device information
`is_partial_lead`	`true` if the lead abandoned the form before completing all steps
`partial_lead_fields`	Array of field names captured for partial leads
`completed_steps`	Array of step identifiers the lead completed
`form_progress`	Completion percentage from 0 to 100
`partial_lead_captured_at`	Timestamp when a partial lead was first captured
`time_to_completion_minutes`	Minutes between partial capture and full completion (if applicable)

Partial Lead Payloads

When a visitor abandons your funnel after entering key information (like email or phone), LeadCapture captures a partial lead. The webhook payload for a partial lead looks like this:

{
  "lead_id": "550e8400-e29b-41d4-a716-446655440000",
  "is_partial_lead": true,
  "partial_lead_fields": ["email", "first_name"],
  "completed_steps": ["step-1"],
  "form_progress": 33,
  "partial_lead_captured_at": "2024-01-15T10:30:00.000Z",
  "email": "john@example.com",
  "first_name": "John"
}

If the same visitor returns and completes the form, the lead record is updated (same lead_id) and a new webhook is sent with is_partial_lead set to false and all fields populated.

Verification and Compliance Fields

If you have verification or compliance features enabled, additional fields are included automatically:

Field	When Included
`email_verified`	When email verification is enabled
`email_verification_status`	When email verification is enabled (valid, invalid, disposable, catchall, unknown)
`phone_verified`	When phone verification (OTP) is enabled
`xxTrustedFormCertUrl`	When TrustedForm is enabled (customizable field name)
`consent_text`	When consent blocks are configured (customizable field name per block)

Pro Tips

Use JSON format unless your receiving system specifically requires XML or Form Data.
The is_partial_lead field lets you filter partial vs. complete leads in your CRM workflow.
System field names can be customized per webhook. See the "Field Mapping and Data Transformations" article for details.
Consent block text is included as plain text in the payload (markdown links are stripped).