How to Send Website Form Leads to Your CRM with a Webhook
A step-by-step guide to posting website form leads straight into your CRM with a webhook: the JSON payload, the auth header, capturing UTM, fbclid and ad IDs, browser vs server calls, error codes and a testing checklist.
Written by Qualimize Team
Founder, Qualimize
- Published
- Last updated
- Reading time
- 11 min read
Table of contents
- 01 The short answer
- 02 What a lead webhook actually is
- 03 The payload: what to send
- 04 Capturing UTM, fbclid and ad IDs on the page
- 05 Browser call or server-side call?
- 06 Responses, errors and retries
- 07 A testing checklist before you go live
Full article
The short answer
To send website form leads to your CRM with a webhook, make your form POST a JSON body (name, phone, email, plus any tracking fields) to the CRM's webhook URL with a secret token in the Authorization header. The CRM checks the token, creates the lead, assigns it and replies with a success code. Everything else in this guide is about doing that reliably: capturing the right tracking data, keeping the token safe, and handling the errors.
A webhook replaces the two habits most small businesses start with: a form that emails the owner, and a form that writes to a Google Sheet someone checks twice a day. Both work until the day nobody opens the inbox, or two reps call the same person. A webhook puts the lead in the same queue as your Meta Instant Form leads, with the same assignment rules and follow-up reminders.
If your website traffic comes from Meta ads, the webhook is also where ad attribution is won or lost. A lead that arrives without the campaign, ad set and ad it came from can never be counted in cost per qualified lead by ad, and cannot be matched well when you send its outcome back to Meta.
What a lead webhook actually is
A webhook is just a URL that accepts an HTTP POST. Your form, or your website's server, sends the lead's details to that URL the moment the visitor clicks Submit. There is no polling, no CSV and no copy-paste: one request, one lead.
Three pieces have to line up. The URL tells the request where to go. The token, sent in an Authorization header as 'Bearer' followed by the secret, tells the CRM which workspace the lead belongs to and proves the request is allowed. The JSON body carries the lead itself. If any of the three is wrong, the CRM should refuse the request with a clear error code rather than silently dropping it.
Many form builders and website plugins have a 'webhook' or 'send to URL' option, sometimes only on paid tiers. If yours does, you may not need a developer at all. If your site is custom-built, the whole integration is usually 20 to 40 lines of code in the form's submit handler.
- URL: the CRM's webhook endpoint, always HTTPS
- Header: Authorization: Bearer <your token>, plus Content-Type: application/json
- Body: the lead's contact details, tracking fields and any extra form answers
- Response: a success code with the new lead's ID, or an error code that says what went wrong
The payload: what to send
Send the fields the CRM needs to create and route the lead, then the fields that explain where the lead came from, then anything else the form asked. As a concrete example, here is how Qualimize's lead webhook (POST /api/webhooks/lead) is laid out; most CRM webhooks follow a similar shape, so check your own CRM's documentation for exact field names.
Core fields: name, phone, email and source (a short label for which form it was, such as 'home-page' or 'pricing-form'). At least one of name, phone or email must be present or the lead is rejected. Everything else is optional and never blocks the lead from being created.
Attribution fields: utm_source, utm_medium, utm_campaign, utm_term, utm_content, fbclid, fbc, fbp, gclid, landing_page and referrer. Ad identity fields: campaign_id, adset_id, ad_id, campaign_name, adset_name, ad_name, placement and site_source_name. Extra questions go in an answers object of flat text values, for example { "budget": "40-60 lakh", "locality": "Baner" }; up to 30 keys are kept and each value is capped at 1,000 characters.
Example request body for a Pune property enquiry: { "name": "Rohit Kulkarni", "phone": "+919800000000", "email": "rohit@example.com", "source": "2bhk-landing", "utm_source": "facebook", "ad_id": "120210000000000000", "answers": { "budget": "60-80 lakh" } }. The name, number and IDs are made up for illustration.
Capturing UTM, fbclid and ad IDs on the page
The webhook can only store what the page sends, and the page only knows what was in the landing URL and the browser's cookies. So before you write the submit handler, decide where each tracking field comes from.
UTM parameters and fbclid come from the landing page URL. Meta adds fbclid to the link when someone clicks an ad. The _fbp cookie is set by the Meta Pixel on your domain, and _fbc holds the click ID; Meta's documentation says that when fbclid is in the URL but there is no _fbc cookie, you can build the fbc value yourself in the format fb.1.<creation time in milliseconds>.<fbclid>, keeping the fbclid exactly as received.
Neither fbclid nor UTMs tell you which ad the person clicked. fbclid is opaque, and UTMs are free text someone typed. To get the real ad, paste dynamic URL parameters into Ads Manager (Ad, then Tracking, then URL parameters), for example ad_id={{ad.id}}&adset_id={{adset.id}}&campaign_id={{campaign.id}}. Meta replaces each {{...}} macro with the real value when it serves the ad, and your form reads them from the URL like any other parameter.
Two traps catch most teams. First, visitors rarely submit on the page they land on; store the parameters in a first-party cookie or session storage on arrival so a form three clicks later still sends them. Second, if the link is opened outside a paid ad (a shared link, an ad preview, an organic post), the macros arrive unexpanded as literal text like {{ad.id}}. Drop any value that still contains double curly braces; storing it creates a fake ad in every report.
Browser call or server-side call?
You can call the webhook straight from the visitor's browser with fetch(), or have your own server receive the form and forward it. Both are valid; they trade convenience for control.
A browser call is the quickest to build and automatically carries the visitor's real IP address and user agent, which help Meta match the person if the lead's outcome is later sent through the Conversions API. The cost is that the token sits in your page's JavaScript, where anyone can read it. Treat a browser token as write-only and low-value: it can create leads in your CRM but should not be able to read anything. Use one token per site, and revoke and replace it if spam starts arriving.
A server-side call keeps the token secret and lets you add your own spam checks, such as a captcha or rate limit, before forwarding. The catch is that the CRM now sees your server's IP and user agent instead of the visitor's. Forward the visitor's values explicitly (in Qualimize's webhook these are client_ip_address and client_user_agent), otherwise every lead records the same server address, which no ad platform can match to a person.
Responses, errors and retries
A good webhook answers every request with a status code and a short machine-readable reason. Your form should read it, show the visitor a friendly message, and log the failure somewhere you will see it. A form that shows 'Thank you' no matter what the CRM replied is how leads disappear without anyone noticing.
Retry only the errors that can succeed on a second try. A 503 means a temporary problem on the CRM side and is safe to retry after a few seconds. A 401, 400 or 422 will fail the same way every time until you fix the token or the payload, so retrying just hides the problem. Keep any request ID the CRM returns in a response header (X-Request-Id in the example webhook); it lets support find the exact request in their logs.
Retries and impatient visitors who click Submit twice can create the same person twice. Pick a CRM that flags possible duplicates by phone and email rather than one that either blocks them silently or lets them through unmarked, so your team sees the repeat and decides.
A testing checklist before you go live
Test with real requests, not just a form that looks right. Ten minutes here saves a month of lost website leads.
Run the checks in order, with a test lead name you will recognise and delete afterwards. In Qualimize, the website webhook settings show recent website leads and include a panel to send a test lead with a pasted token, which confirms the endpoint and token work before you touch your site.
- Send a request with no token: expect 401, and no lead created
- Send a valid request with only a phone number: expect success and a lead in the CRM
- Open your landing page with ?utm_source=test&fbclid=abc123&ad_id=999 in the URL, submit the form, and check that all three values appear on the lead
- Open the page with a literal ad_id={{ad.id}} and confirm the lead does not show {{ad.id}} as its ad
- Navigate to a second page before submitting and confirm the tracking values survived
- Submit the same phone twice and confirm the second lead is flagged as a possible duplicate
- Confirm the lead was auto-assigned and the rep got a notification
Comparison tables
Calling the webhook from the browser vs from your server
| Factor | Browser call (fetch from the page) | Server-side call |
|---|---|---|
| Build effort | Lowest: a few lines in the submit handler | Higher: needs your own backend route |
| Token exposure | Visible in page source; use a write-only, revocable token | Stays secret on your server |
| Visitor IP and user agent | Sent automatically with the request | Must be forwarded explicitly in the body |
| Spam control | Relies on the form builder or CRM | You can add captcha, rate limits and checks first |
| Cookie access (_fbp, _fbc) | Read directly in JavaScript | Must be passed from the browser to your server |
| Best for | Static sites, landing pages, quick launches | Custom sites with a backend, high-spam forms |
Example webhook responses and what to do about each
| Status | Meaning (example webhook) | Retry? | What to fix |
|---|---|---|---|
| 201 | Lead created; body returns the lead ID | No | Nothing |
| 400 | Body was not valid JSON | No | Send JSON with Content-Type: application/json |
| 401 | Token missing, wrong or revoked | No | Check the Authorization: Bearer header and the token |
| 403 | Workspace is not active | No | Check the CRM account status |
| 405 | Used GET instead of POST | No | Send a POST request |
| 422 | None of name, email or phone was sent | No | Check the form's field names |
| 503 | Temporary database error on the CRM side | Yes, after a short wait | Nothing on your side; retry |
FAQ
How do I connect my website contact form to my CRM?
Get the CRM's webhook URL and an API token, then make the form send a POST request with a JSON body (name, phone, email and tracking fields) to that URL, with the token in an Authorization: Bearer header. Many form builders have a webhook option; on a custom site it is a short fetch() call in the submit handler. Test with a real submission before going live.
How do I track which Facebook ad a website lead came from?
Add dynamic URL parameters such as ad_id={{ad.id}}, adset_id={{adset.id}} and campaign_id={{campaign.id}} in Ads Manager under the ad's Tracking section. Meta fills them in when it serves the ad. Your landing page reads them from the URL, keeps them in a cookie until the form is submitted, and sends them to the CRM with the lead. UTMs and fbclid alone cannot identify the ad.
Is it safe to put a CRM API token in website JavaScript?
Only if the token is write-only and limited to creating leads, because anyone can read it in the page source. The worst case is then spam leads, not data theft. Use a separate token per site and revoke it if abused. If the token can read or change data, call the CRM from your own server instead.
What is fbc and fbp, and should I send them with my form leads?
_fbp is a browser ID cookie set by the Meta Pixel, and _fbc holds the ad click ID built from fbclid. Meta recommends sending both with Conversions API events when available because they improve matching. Read them from the cookies when the form is submitted and include them in the webhook body; if only fbclid is present, Meta's documentation explains how to build fbc from it.
Why are my website leads showing {{ad.id}} instead of a real ad ID?
Meta only replaces dynamic macros when it serves a paid ad. If the tracking link was opened from an ad preview, an organic post, a bio link or a shared URL, the literal text arrives instead. Have your form or CRM ignore any value that still contains double curly braces, so those leads are treated as untracked instead of being credited to a fake ad.
Where does Qualimize fit?
Qualimize gives each workspace a lead webhook with per-site tokens, so website form leads land in the same pipeline as Meta Instant Form leads, with UTMs, fbclid and ad IDs captured, unexpanded {{...}} macros dropped, duplicates flagged and auto-assignment applied. That matters if you run Meta ads to a website and want cost per qualified lead by ad. If your forms only go to email and you get a handful of leads a month, a webhook of any kind may be more than you need.
Key takeaways
- A lead webhook is one POST request: URL, a Bearer token in the Authorization header, and a JSON body with the lead.
- Require only one contact field and make every tracking field optional, so a missing UTM never blocks a lead.
- UTMs and fbclid do not identify an ad; dynamic URL parameters like ad_id={{ad.id}} in Ads Manager do.
- Store tracking values on arrival, drop unexpanded {{...}} macros, and forward the visitor's IP and user agent on server-side calls.
- Retry only temporary errors such as 503, show real errors to yourself, and test seven cases before going live.