Custom Webhook best practices

Custom webhooks let you send any event from any system into FunnelTrack. That covers CRM stage changes, backend cron jobs, checkouts on platforms without a native integration, or anywhere your business data lives. This guide covers how to design a payload that matches to the right contact, avoids duplicates, and reaches every ad platform with strong quality signals.

Check the sources list first. If we already integrate with your source (Jotform, ClickFunnels 2.0, HighLevel, Calendly, CallRail, Elementor, Gravity Forms, Typeform, Unbounce, Shopify, WooCommerce, Stripe), use that path. Native integrations handle payload shape, session stitching, and field mapping for you.

Reach for a custom webhook when:

• •Your source system isn't natively supported (many CRMs, billing systems, custom apps)
• •You need to send CRM events like opportunity stage changes, account created, deal won, or subscription upgraded
• •You're sending backend events like batch imports, offline conversion uploads, or scheduled cron
• •You want granular control over which specific event names fire and when

Every event is either web or offline. The difference isn't where the event was fired from. It's whether the visitor was in a browser session on your site at the moment they converted.

Web events happen in a browser session. The visitor is on your site (or a linked site you control) when the event fires. Examples:

• •On-site account creation (account_created)
• •Checkout completed in the browser
• •Form submission on a page where the pixel is loaded

Offline events happen outside a browser session. Examples:

• •CRM stage changes like deal_won or opportunity moved to Closed Won
• •Phone-based sales, in-person transactions, POS closes
• •Batch imports from a system of record (legacy database, spreadsheet backfill)
• •Subscription rebills, refunds, lifecycle updates

For a web event, include the visitor's session identifiers so FunnelTrack can match the webhook to their earlier pageviews. The strongest signals are FunnelTrack's own cookies.

How to read _ft_uid and _ft_sid

There are three ways to grab these cookies depending on where your webhook fires from. Pick whichever matches your setup.

A. Client-side JavaScript (form embeds, on-page fetch)

If your webhook fires from browser JavaScript, read the cookies directly:

function getCookie(name) {
  const m = document.cookie.match('(^|;)\\s*' + name + '=([^;]+)');
  return m ? decodeURIComponent(m.pop()) : '';
}

fetch('https://your-webhook-proxy.example.com/convert', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    event_name: 'account_created',
    event_id: 'USR-8472',
    // ... other fields ...
    web_data: {
      ft_uid: getCookie('_ft_uid'),
      ft_sid: getCookie('_ft_sid'),
      page_url: window.location.href
    }
  })
});

B. Server-side on the same domain (WordPress, Rails, Django, Node)

If your webhook fires from your backend on a page load (thank-you page render, post-checkout webhook fired server-side), read the cookies from the inbound request:

// PHP (WordPress, custom PHP)
$ft_uid = $_COOKIE['_ft_uid'] ?? '';
$ft_sid = $_COOKIE['_ft_sid'] ?? '';

# Python (Django, Flask)
ft_uid = request.COOKIES.get('_ft_uid', '')
ft_sid = request.COOKIES.get('_ft_sid', '')

// Node.js (Express, Next.js API route)
const ft_uid = req.cookies['_ft_uid'] || '';
const ft_sid = req.cookies['_ft_sid'] || '';

C. URL params on cross-domain handoffs

When a visitor moves from your main site to a separate domain (for example store.example.com to checkout.example.com), cookies don't travel with them. The FunnelTrack pixel detects cross-domain links to your configured domain list and appends _ft and _ft_uid as URL parameters. On the destination page, parse them:

const url = new URL(window.location.href);

// Prefer URL params (fresh cross-domain handoff), fall back to cookies.
const ft_uid = url.searchParams.get('_ft_uid') || getCookie('_ft_uid');

// _ft param format is: <sid>.<timestamp>
const ft = url.searchParams.get('_ft');
const ft_sid = ft ? ft.split('.')[0] : getCookie('_ft_sid');

For an offline event, FunnelTrack matches the incoming event to an existing contact via user_data. Email and phone do most of the work. When a match hits, the contact's prior session context (landing page, first-touch source, captured Meta and Google click IDs) gets attached to the outbound dispatch automatically. You send identity. You get attribution enrichment for free.

Optional but powerful: ft_uid if you stored it

If your source system (CRM, custom app) captured the FunnelTrack visitor's _ft_uid at lead-form time, include it in the payload when you later fire an offline conversion for that same person (deal won, contract signed, subscription upgraded):

{
  "event_name": "deal_won",
  "user_data": {
    "email": "marcus.hayes@example.com",
    "phone": "+14155550198",
    "ft_uid": "b5c6d7e8-1a2b-4c3d-9e5f-6a7b8c9d0e1f.2f3e4d5c6b7a8f9e"
  }
}

This is the strongest offline match. Better than email or phone alone (both can miss on typos, work-vs-personal email switches, or number changes). If you're building an offline pipeline from a CRM you control, plan to capture _ft_uid at lead-form time and store it as a custom field on the contact record. Every offline conversion webhook after that carries a perfect join back to the original web session.

Originating click IDs for Google Ads Enhanced Conversions

If your source system captured click IDs at lead-form time (gclid, fbclid, wbraid, gbraid, msclkid, ttclid), send them with the offline event:

{
  "event_name": "deal_won",
  "user_data": { "email": "marcus.hayes@example.com" },
  "click_ids": {
    "gclid": "Cj0KCQjw...",
    "fbclid": "IwAR3..."
  }
}

Google Ads Enhanced Conversions for Leads matches offline uploads to clicks primarily via gclid. If you don't send the originating click ID, Google falls back to identity-hash matching, which has a lower match rate.

Send event_time as a Unix timestamp in seconds (integer, UTC). Every language has a one-line function for this.

{
  "event_time": 1785276396
}

• •HTTP method: POST only. GET, PUT, PATCH, DELETE are rejected.
• •Content-Type: application/json is recommended. We also accept application/x-www-form-urlencoded for legacy senders. Bracket-notation nested keys (user_data[email]) get flattened server-side.
• •Encoding: UTF-8. Non-UTF-8 encodings will be rejected.
• •HTTPS only.Every FunnelTrack webhook URL is HTTPS. Don't downgrade to HTTP.
• •Payload size:under 100 KB is ideal. 1 MB is the hard cap. Don't send base64-encoded receipts, images, or full call transcripts.
• •Response: we respond with 200 OK on accepted, 400 on malformed, 401 on bad API key, 413 on oversized payload, and 429 on rate-limited. Retry on 429 and 5xx only.
• •Retry policy: if you retry, use the same event_id. FunnelTrack sees the duplicate and won't create a second conversion.

Anything under a top-level custom_paramsobject becomes available for field mapping to destination event parameters (Meta's custom_data, GA4 event params, TikTok properties). Use it for:

• •Lead scores, deal stages, subscription tiers, or any other attribute the ad platform can bid on
• •Internal categorization your team uses (sales rep, source campaign, funnel step)
• •Product or plan identifiers for retargeting audience membership

{
  "custom_params": {
    "plan_tier": "pro",
    "lead_score": 87,
    "sales_rep": "j_ortega",
    "referral_code": "PARTNER-24"
  }
}

Configure filter conditions on the event card so the webhook only creates events when the payload matches. Common patterns:

• •Stage filter: stage == "Closed Won". Only fire on wins, not every stage change.
• •Value floor: value > 500. Only fire for meaningful conversions.
• •Type filter: product_type != "internal_test". Exclude non-customer transactions.

Filters run before dedup, dispatch, and usage counting. Filtered events show up in the usage log as filtered (not failed or received) so you can see which criteria are firing.

1. Send a test payload. Use curl, Postman, or your source system's test fire. Verify a 200 OK response.
2. Check the inbound row in Usage Log. Confirm the payload arrived and shows the correct event name.
3. Verify field mapping. Click into the log row. Confirm identity fields, revenue, and event parameters are populated the way you expected.
4. Enable destinations one at a time. Flip Meta on first. Send another test. Verify it appears in Events Manager Test Events. Then GA4. Then Google Ads. Never enable all at once for a new event.
5. Confirm dedup works. Send the exact same payload twice. The second call should show as deduped in the usage log, not counted as a second conversion.
6. Confirm filters work.Send a payload that shouldn't match your filter conditions. Verify it lands as filteredand doesn't reach any destination.

• •Treat the webhook URL as a secret.It contains an API key that authenticates every submission. Don't paste it in public docs, screenshots, or shared spreadsheets.
• •HTTPS only.Every FunnelTrack webhook URL is HTTPS. Don't downgrade to HTTP.
• •Rotate if leaked. Regenerate the endpoint from the Webhooks settings page. The old URL immediately stops accepting submissions.
• •Filter as soft auth.If you're worried about spurious submissions, add a filter like api_source == "our_crm" and only accept payloads from your intended sender.

{
  "event_name": "account_created",
  "event_id": "USR-8472",
  "event_time": 1785276396,
  "user_data": {
    "email": "sarah.chen@example.com",
    "phone": "+12065550142",
    "first_name": "Sarah",
    "last_name": "Chen",
    "city": "Portland",
    "region": "OR",
    "postal_code": "97205",
    "country": "US",
    "external_id": "CRM-77321"
  },
  "web_data": {
    "ft_uid": "a3f2b8c1-9d4e-4f56-8a7b-1c2d3e4f5060.7e8f9a0b1c2d3e4f",
    "ft_sid": "4c8b1a2f-5d6e-4f7a-8b9c-0d1e2f3a4b5c",
    "ip_address": "203.0.113.42",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ...",
    "page_url": "https://example.com/signup/confirm"
  },
  "custom_params": {
    "plan_tier": "pro",
    "signup_source": "google_ads"
  }
}

{
  "event_name": "deal_won",
  "event_id": "OPP-38472",
  "event_time": 1785276396,
  "value": 4200.00,
  "currency": "USD",
  "user_data": {
    "email": "marcus.hayes@example.com",
    "phone": "+14155550198",
    "first_name": "Marcus",
    "last_name": "Hayes",
    "city": "Austin",
    "region": "TX",
    "postal_code": "78701",
    "country": "US",
    "external_id": "CRM-42196",
    "ft_uid": "b5c6d7e8-1a2b-4c3d-9e5f-6a7b8c9d0e1f.2f3e4d5c6b7a8f9e"
  },
  "click_ids": {
    "gclid": "Cj0KCQjw...",
    "fbclid": "IwAR3..."
  },
  "custom_params": {
    "opportunity_stage": "Closed Won",
    "sales_rep": "j_ortega",
    "deal_source": "inbound_lead"
  }
}