Get Started
Get Started
View Categories

Webhooks: Sending UTM and Ad Tracking Data

16 min read

PloverCRM webhooks can receive more than basic contact details. They can also receive visitor attribution data such as UTM parameters, click IDs, referrer information, page URLs, IP address, user agent, and the tracking cookies that PloverCRM normally captures in the browser.

This is useful when a lead is created by an external form, landing page, quiz, ad platform, custom app, automation tool, or server-to-server integration and you want the contact in PloverCRM to keep the same attribution information as a lead captured directly on your WordPress site.

Quick answer #

Send your normal lead fields together with these PloverCRM context fields:

plover_crm_current_url
plover_crm_referer
plover_crm_user_ip
plover_crm_user_agent
plover_crm_cookies

Put UTM values and ad click IDs inside plover_crm_cookies using PloverCRM’s tracking field names.

Example:

{
  "email": "[email protected]",
  "first_name": "John",
  "last_name": "Smith",
  "phone": "+15551234567",

  "plover_crm_current_url": "https://example.com/pricing?utm_source=google&utm_medium=cpc&utm_campaign=spring-sale&gclid=test-gclid",
  "plover_crm_referer": "https://www.google.com/",
  "plover_crm_user_ip": "203.0.113.42",
  "plover_crm_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 Chrome/124.0 Safari/537.36",

  "plover_crm_cookies": {
    "plover_crm_utm_source": "google",
    "plover_crm_utm_medium": "cpc",
    "plover_crm_utm_campaign": "spring-sale",
    "plover_crm_utm_term": "crm software",
    "plover_crm_utm_content": "pricing-ad",
    "plover_crm_gclid": "test-gclid",
    "plover_crm_referral_domain": "google.com",
    "plover_crm_landing_page_first_visit": "https://example.com/?utm_source=google&utm_medium=cpc&utm_campaign=spring-sale&gclid=test-gclid",
    "plover_crm_landing_datetime_first_visit": "2026-05-13 10:15:00",
    "plover_crm_last_utm_source": "google",
    "plover_crm_last_utm_medium": "cpc",
    "plover_crm_last_utm_campaign": "spring-sale",
    "plover_crm_last_utm_term": "crm software",
    "plover_crm_last_utm_content": "pricing-ad",
    "plover_crm_last_referral_domain": "google.com",
    "plover_crm_last_page_url": "https://example.com/pricing?utm_source=google&utm_medium=cpc&utm_campaign=spring-sale&gclid=test-gclid",
    "plover_crm_last_seen_at": "2026-05-13 10:20:00"
  }
}

You do not need to send every tracking field. Send the values your source system knows. PloverCRM will use what is present and leave the rest blank.

How webhook tracking works #

When PloverCRM receives a webhook, it handles two related jobs:

  1. Lead/contact creation — the webhook payload is processed through the Data Sources mapping pipeline. Your mapped fields create or update the contact.
  2. Contact enrichment — visitor context from the webhook payload is used to populate tracking, attribution, device, referrer, page, and IP information on the contact.

These two jobs are connected but not identical.

Normal lead fields such as email, first_name, phone, company, and custom answers are fields you map in the webhook data source setup.

Tracking context fields such as plover_crm_user_ip, plover_crm_user_agent, plover_crm_current_url, plover_crm_referer, and plover_crm_cookies are treated as operational context for enrichment. PloverCRM intentionally hides these transport fields from submitted-data displays and mapping discovery, because they are not ordinary customer form answers.

Webhook endpoint #

Each PloverCRM webhook has a unique URL like this:

https://your-site.com/wp-json/plover-crm/v1/webhook/incoming/YOUR_WEBHOOK_TOKEN

Send a POST request to that URL.

PloverCRM accepts JSON payloads and form-encoded payloads. JSON is recommended for tracking data because plover_crm_cookies can be sent as a nested object.

Example request:

curl -X POST "https://your-site.com/wp-json/plover-crm/v1/webhook/incoming/YOUR_WEBHOOK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "first_name": "John",
    "plover_crm_current_url": "https://example.com/pricing?utm_source=google&utm_medium=cpc&utm_campaign=spring-sale",
    "plover_crm_referer": "https://www.google.com/",
    "plover_crm_user_ip": "203.0.113.42",
    "plover_crm_user_agent": "Mozilla/5.0",
    "plover_crm_cookies": {
      "plover_crm_utm_source": "google",
      "plover_crm_utm_medium": "cpc",
      "plover_crm_utm_campaign": "spring-sale"
    }
  }'

Recommended payload structure #

A complete webhook payload can include:

  • Contact identity fields.
  • Any custom submitted fields you want to map.
  • PloverCRM visitor context fields.
  • PloverCRM tracking cookies.

Example:

{
  "email": "[email protected]",
  "first_name": "Alice",
  "last_name": "Example",
  "phone": "+15550123456",
  "company": "Example Ltd",

  "message": "I would like a demo.",
  "plan_interest": "Professional",

  "fields": [
    { "id": "budget", "value": "5000" },
    { "id": "timeline", "value": "This month" }
  ],

  "plover_crm_current_url": "https://example.com/demo?utm_source=facebook&utm_medium=paid_social&utm_campaign=demo-campaign&fbclid=fb.123",
  "plover_crm_referer": "https://facebook.com/",
  "plover_crm_user_ip": "203.0.113.42",
  "plover_crm_user_agent": "Mozilla/5.0",

  "plover_crm_cookies": {
    "plover_crm_utm_source": "facebook",
    "plover_crm_utm_medium": "paid_social",
    "plover_crm_utm_campaign": "demo-campaign",
    "plover_crm_utm_content": "lead-form-ad",
    "plover_crm_fbclid": "fb.123",
    "plover_crm_referral_domain": "facebook.com",
    "plover_crm_landing_page_first_visit": "https://example.com/demo?utm_source=facebook&utm_medium=paid_social&utm_campaign=demo-campaign&fbclid=fb.123",
    "plover_crm_landing_datetime_first_visit": "2026-05-13 10:15:00",
    "plover_crm_last_utm_source": "facebook",
    "plover_crm_last_utm_medium": "paid_social",
    "plover_crm_last_utm_campaign": "demo-campaign",
    "plover_crm_last_utm_content": "lead-form-ad",
    "plover_crm_last_referral_domain": "facebook.com",
    "plover_crm_last_page_url": "https://example.com/demo?utm_source=facebook&utm_medium=paid_social&utm_campaign=demo-campaign&fbclid=fb.123",
    "plover_crm_last_seen_at": "2026-05-13 10:20:00"
  }
}

Required and optional context fields #

plover_crm_current_url #

The page URL where the lead submitted the form or completed the conversion.

Example:

"plover_crm_current_url": "https://example.com/pricing?utm_source=google&utm_medium=cpc&utm_campaign=spring-sale"

PloverCRM can read UTM parameters and click IDs directly from this URL if they are present. This URL is also saved as the submission URL and can be used as the last page URL.

plover_crm_referer #

The previous page or external referrer URL.

Example:

"plover_crm_referer": "https://www.google.com/"

PloverCRM can derive the referrer domain from this URL when a separate referral-domain cookie is not provided.

plover_crm_user_ip #

The visitor’s IP address.

Example:

"plover_crm_user_ip": "203.0.113.42"

Important: for webhook-origin contacts, PloverCRM only trusts an IP address explicitly sent in the payload. It does not use the webhook request sender’s server IP as the visitor IP, because server-to-server webhooks often come from the source platform, automation tool, or hosting server rather than the actual visitor.

plover_crm_user_agent #

The visitor’s browser user agent.

Example:

"plover_crm_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 Chrome/124.0 Safari/537.36"

PloverCRM uses this for device, operating system, and browser enrichment.

plover_crm_cookies #

An object containing PloverCRM tracking cookie values.

Example:

"plover_crm_cookies": {
  "plover_crm_utm_source": "google",
  "plover_crm_utm_medium": "cpc",
  "plover_crm_utm_campaign": "spring-sale",
  "plover_crm_gclid": "test-gclid"
}

Use PloverCRM’s exact tracking names for automatic attribution enrichment.

Supported automatic tracking fields #

The following fields are recognized inside plover_crm_cookies.

First-touch UTM fields #

These describe the original campaign or source that first brought the visitor to the site. If the contact already has a first-touch value, PloverCRM keeps the existing first-touch value instead of overwriting it.

plover_crm_utm_id
plover_crm_utm_source
plover_crm_utm_medium
plover_crm_utm_campaign
plover_crm_utm_term
plover_crm_utm_content

First-touch ad click IDs #

These are click identifiers from ad platforms. Like first-touch UTM fields, existing values are preserved when already present on the contact.

plover_crm_gclid
plover_crm_gbraid
plover_crm_wbraid
plover_crm_fbclid
plover_crm_msclkid
plover_crm_ttclid
plover_crm_li_fat_id
plover_crm_twclid

Common sources:

FieldTypical platform
plover_crm_gclidGoogle Ads
plover_crm_gbraidGoogle Ads app/web attribution
plover_crm_wbraidGoogle Ads web-to-app/iOS attribution
plover_crm_fbclidMeta/Facebook
plover_crm_msclkidMicrosoft Ads
plover_crm_ttclidTikTok Ads
plover_crm_li_fat_idLinkedIn Ads
plover_crm_twclidX/Twitter Ads

Referral fields #

plover_crm_referral_domain
plover_crm_last_referral_domain

If plover_crm_referral_domain is missing, PloverCRM can derive the first-touch referral domain from plover_crm_referer.

If plover_crm_last_referral_domain is missing, PloverCRM can derive the last-touch referral domain from plover_crm_referer.

Landing and visit fields #

plover_crm_landing_page_first_visit
plover_crm_landing_datetime_first_visit
plover_crm_last_page_url
plover_crm_last_seen_at

These preserve the first page, first visit time, latest page, and latest seen time known by your source system.

If no first landing page is sent, PloverCRM can use plover_crm_current_url when it contains tracking parameters.

If no last page URL is sent, PloverCRM can use plover_crm_current_url.

If no last seen time is sent but a current page or last-touch data exists, PloverCRM can set the last seen time during enrichment.

Last-touch UTM fields #

These describe the latest campaign/source associated with the conversion or most recent tracked visit.

plover_crm_last_utm_source
plover_crm_last_utm_medium
plover_crm_last_utm_campaign
plover_crm_last_utm_term
plover_crm_last_utm_content

PloverCRM can also read last-touch UTM values from plover_crm_current_url or plover_crm_last_page_url if those URLs include UTM query parameters.

Query parameters PloverCRM can read from URLs #

If your plover_crm_current_url, plover_crm_landing_page_first_visit, or plover_crm_last_page_url contains tracking query parameters, PloverCRM can extract supported values from those URLs.

Supported first-touch query parameters:

utm_id
utm_source
utm_medium
utm_campaign
utm_term
utm_content
gclid
gbraid
wbraid
fbclid
msclkid
ttclid
li_fat_id
twclid

Supported last-touch query parameters:

utm_source
utm_medium
utm_campaign
utm_term
utm_content

For the most reliable results, send both:

  1. The full URL in plover_crm_current_url.
  2. The parsed tracking values inside plover_crm_cookies.

That gives PloverCRM enough information even if one source does not contain every value.

First-touch vs last-touch behavior #

PloverCRM separates first-touch attribution from last-touch attribution.

First-touch fields #

First-touch fields represent the original acquisition source. PloverCRM does not overwrite first-touch fields that already exist on the contact.

Examples:

plover_crm_utm_source
plover_crm_utm_medium
plover_crm_utm_campaign
plover_crm_gclid
plover_crm_fbclid
plover_crm_referral_domain
plover_crm_landing_page_first_visit
plover_crm_landing_datetime_first_visit

Last-touch fields #

Last-touch fields represent the latest known visit or conversion source. These can be updated when a later webhook submission provides new values.

Examples:

plover_crm_last_utm_source
plover_crm_last_utm_medium
plover_crm_last_utm_campaign
plover_crm_last_referral_domain
plover_crm_last_page_url
plover_crm_last_seen_at

Custom field names vs PloverCRM field names #

Use PloverCRM field names when you want automatic tracking enrichment.

Good:

{
  "plover_crm_cookies": {
    "plover_crm_gclid": "EAIaIQob...",
    "plover_crm_utm_source": "google"
  }
}

Not automatic:

{
  "google_click_id": "EAIaIQob...",
  "utmSource": "google"
}

Custom names like google_click_id or utmSource can still be sent as normal webhook fields. You can map them manually in your webhook data source setup if you want them stored in a custom field. However, PloverCRM’s automatic attribution logic expects the PloverCRM tracking names listed in this article.

Sending additional ad metadata #

Campaign names, ad names, ad set IDs, creative IDs, form IDs, and other platform-specific metadata can be included as regular webhook fields.

Example:

{
  "email": "[email protected]",
  "first_name": "John",

  "meta_campaign_name": "Spring Sale",
  "meta_adset_name": "Retargeting - 30 days",
  "meta_ad_name": "Pricing Page Ad A",
  "meta_lead_form_id": "123456789",

  "google_campaign_id": "987654321",
  "google_adgroup_id": "123456789",
  "google_ad_id": "456789123",

  "plover_crm_cookies": {
    "plover_crm_fbclid": "fb.123",
    "plover_crm_utm_source": "facebook",
    "plover_crm_utm_medium": "paid_social"
  }
}

The extra ad metadata fields are not automatically interpreted as PloverCRM tracking cookies. Map them manually if you want them stored on the contact.

Nested fields and arrays #

Webhook payloads can contain nested objects and arrays. PloverCRM flattens them into dot-notation keys for mapping.

Nested object example:

{
  "customer": {
    "address": {
      "city": "Phoenix"
    }
  }
}

Mapping key:

customer.address.city

Array-of-fields example:

{
  "fields": [
    { "id": "budget", "value": "5000" },
    { "id": "timeline", "value": "This month" }
  ]
}

Mapping keys:

fields
fields.budget
fields.timeline

For indexed arrays of objects, PloverCRM uses one of these item properties as the dot-notation segment when present:

id
key
name
slug

If the object also has a value property, that value is used as the mapped field value.

Field discovery and submitted data visibility #

When PloverCRM receives a webhook, it stores the latest payload so the data source setup screen can discover fields for mapping.

However, PloverCRM hides operational tracking context from mapping discovery and submitted-data summaries, including:

plover_crm_current_url
plover_crm_referer
plover_crm_user_ip
plover_crm_user_agent
plover_crm_cookies
plover_crm_cookies.*

This is expected. These fields are used internally for contact enrichment. They are not ordinary form answers.

Other submitted fields, such as email, first_name, message, fields.budget, or custom ad metadata, can appear in discovery and can be mapped.

Accepted aliases #

PloverCRM prefers the plover_crm_* context field names, but it can also understand a few generic aliases.

Preferred:

{
  "plover_crm_user_ip": "203.0.113.42",
  "plover_crm_user_agent": "Mozilla/5.0",
  "plover_crm_current_url": "https://example.com/pricing",
  "plover_crm_referer": "https://google.com/",
  "plover_crm_cookies": {}
}

Also accepted:

{
  "user_ip": "203.0.113.42",
  "ip": "203.0.113.42",
  "user_agent": "Mozilla/5.0",
  "current_url": "https://example.com/pricing",
  "referrer_url": "https://google.com/",
  "referer_url": "https://google.com/",
  "cookies": {}
}

For clarity and future compatibility, use the preferred plover_crm_* names in new integrations.

Important warning about IP addresses #

Do not rely on the webhook HTTP request IP as the visitor IP.

Many webhooks are sent by servers, automation platforms, CRMs, landing page builders, or queue workers. In those cases, the request IP belongs to the sender platform, not the person who submitted the lead form.

For webhook-origin contacts, PloverCRM only uses visitor IP information that is explicitly included in the payload, such as:

{
  "plover_crm_user_ip": "203.0.113.42"
}

If no visitor IP is sent, PloverCRM leaves the webhook visitor IP empty rather than saving an incorrect server IP.

Minimal examples #

Basic UTM payload #

{
  "email": "[email protected]",
  "first_name": "Lead",
  "plover_crm_current_url": "https://example.com/contact?utm_source=newsletter&utm_medium=email&utm_campaign=may-offer",
  "plover_crm_cookies": {
    "plover_crm_utm_source": "newsletter",
    "plover_crm_utm_medium": "email",
    "plover_crm_utm_campaign": "may-offer"
  }
}

Google Ads payload #

{
  "email": "[email protected]",
  "first_name": "Lead",
  "plover_crm_current_url": "https://example.com/demo?utm_source=google&utm_medium=cpc&utm_campaign=brand&gclid=EAIaIQobExample",
  "plover_crm_referer": "https://www.google.com/",
  "plover_crm_user_ip": "203.0.113.42",
  "plover_crm_user_agent": "Mozilla/5.0",
  "plover_crm_cookies": {
    "plover_crm_utm_source": "google",
    "plover_crm_utm_medium": "cpc",
    "plover_crm_utm_campaign": "brand",
    "plover_crm_gclid": "EAIaIQobExample",
    "plover_crm_referral_domain": "google.com",
    "plover_crm_last_page_url": "https://example.com/demo?utm_source=google&utm_medium=cpc&utm_campaign=brand&gclid=EAIaIQobExample"
  }
}

Meta/Facebook Ads payload #

{
  "email": "[email protected]",
  "first_name": "Lead",
  "plover_crm_current_url": "https://example.com/offer?utm_source=facebook&utm_medium=paid_social&utm_campaign=retargeting&fbclid=fb.123",
  "plover_crm_referer": "https://facebook.com/",
  "plover_crm_cookies": {
    "plover_crm_utm_source": "facebook",
    "plover_crm_utm_medium": "paid_social",
    "plover_crm_utm_campaign": "retargeting",
    "plover_crm_fbclid": "fb.123",
    "plover_crm_referral_domain": "facebook.com",
    "plover_crm_last_utm_source": "facebook",
    "plover_crm_last_utm_medium": "paid_social",
    "plover_crm_last_utm_campaign": "retargeting"
  }
}

Microsoft, TikTok, LinkedIn, or X/Twitter payload #

{
  "email": "[email protected]",
  "first_name": "Lead",
  "plover_crm_current_url": "https://example.com/landing?utm_source=linkedin&utm_medium=paid_social&utm_campaign=b2b-demo&li_fat_id=li.123",
  "plover_crm_cookies": {
    "plover_crm_utm_source": "linkedin",
    "plover_crm_utm_medium": "paid_social",
    "plover_crm_utm_campaign": "b2b-demo",
    "plover_crm_li_fat_id": "li.123"
  }
}

Use the relevant click ID field for the platform:

plover_crm_msclkid
plover_crm_ttclid
plover_crm_li_fat_id
plover_crm_twclid

Best practices #

  1. Use JSON when possible. JSON preserves plover_crm_cookies as a nested object.
  2. Use PloverCRM’s exact tracking field names. This enables automatic enrichment.
  3. Send the real visitor IP only if you have it. Do not send your server IP or automation tool IP as plover_crm_user_ip.
  4. Send the full page URL. plover_crm_current_url can contain useful UTM and click-ID query parameters.
  5. Send both first-touch and last-touch values when available. First-touch explains where the lead originally came from; last-touch explains the most recent conversion path.
  6. Map normal lead fields separately. Tracking context enriches the contact, but contact creation still depends on your data source field mappings.
  7. Use custom ad metadata fields for reporting details. Campaign names, ad names, creative IDs, and form IDs can be mapped manually as regular fields.

Troubleshooting #

My webhook was received, but tracking fields are empty #

Check that your tracking values are inside plover_crm_cookies and use exact PloverCRM names such as plover_crm_utm_source or plover_crm_gclid.

Also check that the webhook-created contact has a source recognized as a webhook source. PloverCRM treats Webhook and webhook:{id} contacts as webhook-origin contacts for enrichment.

I do not see plover_crm_cookies in field mapping #

That is expected. PloverCRM hides plover_crm_cookies and other context fields from mapping discovery and submitted-data displays. They are used internally for enrichment.

My visitor IP is wrong or blank #

For webhook-origin contacts, PloverCRM does not use the sender server’s request IP. Send the actual visitor IP explicitly as plover_crm_user_ip if your source platform provides it.

My custom gclid field did not populate Google Click ID automatically #

Automatic enrichment expects:

{
  "plover_crm_cookies": {
    "plover_crm_gclid": "your-gclid"
  }
}

A custom field such as gclid, google_gcl_id, or google_click_id can still be mapped manually, but it is not the automatic tracking-cookie field unless sent as plover_crm_gclid.

First-touch values did not change after a later webhook #

That is expected. First-touch fields are designed to preserve the original acquisition source. Later submissions update last-touch fields such as plover_crm_last_utm_source, plover_crm_last_utm_campaign, and plover_crm_last_page_url.

Summary #

To send UTM and ad tracking data through a PloverCRM webhook, include your normal lead fields plus PloverCRM visitor context fields. Put automatic attribution values inside plover_crm_cookies using PloverCRM’s exact tracking names.

The most important structure is:

{
  "email": "[email protected]",
  "plover_crm_current_url": "https://example.com/page?utm_source=google&utm_medium=cpc&utm_campaign=spring&gclid=test",
  "plover_crm_referer": "https://google.com/",
  "plover_crm_user_ip": "203.0.113.42",
  "plover_crm_user_agent": "Mozilla/5.0",
  "plover_crm_cookies": {
    "plover_crm_utm_source": "google",
    "plover_crm_utm_medium": "cpc",
    "plover_crm_utm_campaign": "spring",
    "plover_crm_gclid": "test"
  }
}

This gives PloverCRM the information it needs to create or update the contact, preserve attribution, record visit context, enrich device and IP details, and keep first-touch and last-touch tracking data accurate.

Updated on May 13, 2026
add-lead api utm-tracking webhooks

What are your Feelings

  • Happy
  • Normal
  • Sad

Get Started with Plover CRM

Tell us a little about your business and what you’re looking to achieve. Our team will help you set up Plover CRM to manage leads, automate workflows, and grow faster with confidence.

Popup Form