Webhooks

Webhooks connect TrueMetriks to pretty much anything. Take conversions in from any tool, and send yours back out to any URL with attribution attached. Here is how both work.

Set this up with AI

Copy this prompt into ChatGPT, Claude or whichever AI you use. It carries this whole guide, the pages it depends on, and a link to every video, so it can walk you through it one step at a time.

Open as text

Webhooks move conversions in and out of TrueMetriks. Open Settings > Integrations > Webhooks and you get two tabs: Receive webhooks brings conversions in, Send webhooks pushes them back out with attribution attached.

Works with any tool that has webhooks

If a tool can send or receive a webhook, it works with TrueMetriks. That is any CRM (HubSpot, Salesforce, Pipedrive, GoHighLevel, Close), any email or SMS platform (ActiveCampaign, Klaviyo, Mailchimp, Kit), Zapier, Make, n8n, form and booking tools, course and membership platforms, and your own backend.

So a tool with no TrueMetriks guide of its own does not need one. Point its webhook at a receiving webhook to bring its conversions in, or add a sending webhook to push your conversions to it with attribution attached.

A tool with no webhooks of its own can still connect through Zapier or Make, which talk to thousands of apps.

Receive webhooks

Bring conversions in from any tool - Zapier, a WordPress form, GoHighLevel, or your own backend. Each webhook gets its own secret URL. Paste that URL into the tool and it sends Leads, booked calls, Purchases or custom events into this site's analytics.

Step 1 - Create a receiving webhook

On the Receive webhooks tab, click Add receiving webhook.

Receive webhooks 3 webhooks

Get conversions INTO TrueMetriks. Each webhook gets its own secret URL - paste it into any tool that can send webhooks.

Lead From GHL Lead ad platforms ON
Store Purchases Purchase
⚠ Stripe is already reporting Purchases for this site - if the same sale also arrives through this webhook it may be counted twice. Matching purchases are paired automatically.

Webhook URL - paste this into the sending tool

https://q.demo-brand.example/api/webhooks/in/dd10d51c9d4fd534d7eb53c768c12d5d4d1b293e9a131b

Also fire to connected ad platforms

Sends matching events to Facebook / TikTok / GA4 / Google Ads exactly like a native integration. Analytics reporting always happens either way.

Recent deliveries (3)
Quiz Completed Hook QuizCompleted
On the Receive webhooks tab, click Add receiving webhook. Each webhook has its own secret URL and an optional Also fire to ad platforms toggle.

Name it after the tool that will send to it, then pick the event type:

  • Lead, Schedule, or Purchase for a standard conversion.
  • Refund to take a refund off a sale TrueMetriks already has. See Refunds.
  • Custom event name for your own event (for example ApplicationSubmitted). Custom events show in analytics and can trigger sending webhooks.

Only Purchase counts as revenue. Total Revenue and ROAS add up Purchase events only. A custom event can carry a value, but that value stays with the event and is never added to Total Revenue or ROAS. If a sale should count, send it as a Purchase. You can fire your custom event as well; it does not count the money twice.

You cannot change the event type later, because tools send to this URL expecting it. If you need a different type, create a second webhook. Click Create webhook.

Add receiving webhook

Name

e.g. Zapier leads

A label just for you - name it after the tool that will send to it.

Event type

Lead

Lead, Schedule, Purchase, or a custom event name. Fixed after creation.

Also fire to connected ad platforms

Sends matching events to Facebook / TikTok / GA4 / Google Ads exactly like a native integration. Analytics reporting always happens either way.

Name the webhook, pick the event type, then click Create webhook. The event type is fixed after creation.

Step 2 - Copy the URL into your tool

Copy the webhook URL and paste it into the tool that will send to it. That is the whole setup. The URL is the only credential, there are no API keys.

Step 3 - Send a payload

POST JSON to the URL (form-encoded works too). We read the common field names, and we find them inside nested payloads too, so most tools work with no setup at all:

curl -X POST 'https://q.your-domain/api/webhooks/in/YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"email":"[email protected]","first_name":"Jane","value":49.99,"currency":"USD"}'

The fields we read are email, phone, first_name, last_name, value, currency and order_id, plus the optional existing_email (see Booked with one email, paid with another). Anything else you send is kept as event properties. If it works you get HTTP 200 back, with a summary of what we found.

The event then shows in your analytics like any other integration. It only gets credited to an ad if we can tell which visitor it came from, and that part is worth getting right, so it has its own section next.

Make sure the conversion lands on the right visitor

When a conversion arrives by webhook, we have to work out which visitor it came from. If we cannot, the sale still counts and the money is still yours, but it lands on a person with no history, so no ad gets the credit.

Most of the time this takes care of itself. Nearly every tool sends us an email, and nearly every buyer types their email somewhere on your site, so the two line up and the conversion joins the right journey. Nothing for you to do. Capturing the email as early as you have it makes this even more reliable - see window.tmIdentify on the Custom install guide.

When email is not enough

Two things break the email match, and both are worth knowing about:

  • They never typed their email on your site. They browsed, then paid somewhere you do not control, so no visit of theirs carries that address. Nothing to match against.
  • They typed it two different ways. One spelling at a booking, another at checkout, and to us that is two different people.

We do repair the obvious misspellings, but only so far. We fix a short, fixed list of provider typos, one way only: an email arriving as gmial.com is also tried as gmail.com. An email that arrives spelled correctly is never checked against misspellings, because that could merge two different people. And a typo before the @ (davd@ for david@) is not fixed at all.

So if your conversions keep landing with no visit attached, email alone is not reaching those buyers, and the next section is how you fix it.

The fix - send us the visitor id

This is optional, and most sites never need it. But when email is not landing, it is the one thing that always works, because there is nothing to match and nothing to guess. Everything else is us working out who someone probably is. This is us being told.

Every visitor we track carries a cookie on your own domain called _evid. Read it in the browser, drop it into a hidden field on your form or checkout, and send it in the payload alongside the email you already send.

You can name the field any of these: evid, _evid, tm_evid, visitor_id, tm_visitor_id, tm_id.

Add the hidden field to your form:

<input type="hidden" name="tm_evid" value="">

Then fill it from the cookie at the moment the form is submitted:

<script>
  document.addEventListener("submit", function (e) {
    var field = e.target.querySelector('input[name="tm_evid"]');
    if (!field) return;
    var match = document.cookie.match(/(?:^|;\s*)_evid=([^;]*)/);
    field.value = match ? decodeURIComponent(match[1]) : "";
  }, true);
</script>

Your payload then carries one extra line:

{
  "email": "[email protected]",
  "value": 49.99,
  "currency": "USD",
  "tm_evid": "ev_k3f9q2_a1b2c3d4"
}

Read the cookie in the browser. Never bake it into the page. If a CDN caches the page holding your hidden field, one visitor's _evid gets saved into the HTML and handed to everybody who loads it after them, and all of their conversions pile onto that one person. We trust the visitor id above everything else, so nothing later catches the mistake. The snippet above is safe because it reads the cookie as the form is sent, in that visitor's own browser.

Send the click id if you have it

fbclid and gclid sit in the landing-page URL, so you can put them in a hidden field the same way, with no cookie to read. Another option when the visitor id is awkward to get at.

You can name the field any of these: fbclid, gclid, click_id, tm_click_id. Any of the four helps us find the visitor.

Only click_id and tm_click_id do a second job: they also pick which ad click we send to your ad platforms. A field named fbclid or gclid never does. See Credit the ad that booked the call.

What we try, in order

  • Visitor id - exact, no guessing.
  • Click id - fbclid, gclid, click_id or tm_click_id, matched against the click ids we stored for that visitor.
  • Email - matched against the email attached to their visits.

We stop at the first one that finds a real visit. For most sites the email on its own gets there, which is why nothing above is required. Sending more than one is safe either way - they do not clash, the strongest one wins.

Why a conversion shows no visit

A conversion with no visit attached means nothing in that payload matched a visitor we had seen. It still counts and the money is still yours, but with no journey behind it there is no ad to credit.

Adding the visitor id fixes it from then on. It cannot go back and fix conversions that already arrived, so the sooner it is in, the sooner your attribution fills in.

Update an existing user

Every receiving webhook delivery records a conversion, such as a Lead, a booked call, a Purchase or your own event name. There is no delivery that only edits a person without recording something.

When the email in the payload belongs to someone we already know, the conversion lands on that existing user's journey. You do not need to do anything extra for that.

What each field does for an existing user:

  • first_name, last_name and phone help your ad platforms match the conversion to the right person. A new value replaces the older one, and an empty value never erases it. They do not change the name shown on the person in TrueMetriks.
  • existing_email adds earlier emails to an existing user, for someone who booked with one email and paid with another. It takes one email or several. See the next section.
  • The email itself cannot be changed. A webhook adds a second email with existing_email, and it never replaces the one we already have.

Booked with one email, paid with another

A lead books a call with one email and pays with another, so to us that is two people, and the sale loses the ad that brought them in.

Fix it in the payload. Keep email as the email they paid with, and add existing_email with the email they booked or signed up with:

{
  "email": "[email protected]",
  "existing_email": "[email protected]",
  "value": 997,
  "currency": "USD",
  "order_id": "INV-1042"
}

Put existing_email at the top level, or inside a customData block if that is where your tool puts its fields. The name has to be exactly existing_email.

When we already know the person with that email, the sale lands on their journey, so the ad that brought them in gets the credit. The paid email is added to their profile as a second email.

When we do not know them yet, the sale is recorded under the paid email, exactly as it would be without existing_email. We keep looking for 24 hours, and the moment they appear (say their booking arrives a little late) we move the sale onto them. If they never appear, the delivery says Existing email not found.

We do not link in two cases:

  • The paid email already belongs to a different person as their second email. One email can belong to one person only, so the sale is recorded under the paid email as usual.
  • existing_email cannot be used. It is not a valid email, it is the same as email, or there is no email in the payload. The sale is recorded as usual and the link is skipped.

You can see what happened in two places. The webhook's response carries a link object next to the usual summary:

{
  "ok": true,
  "event_type": "Purchase",
  "link": { "status": "linked", "existing_email": "[email protected]" }
}

status is linked, pending (we are still looking), conflict (the paid email belongs to someone else, with reason set to paid_email_linked_elsewhere) or ignored (with reason set to invalid_existing_email, same_as_email or no_paid_email).

Recent deliveries shows the same outcome at the end of each line:

Only receiving webhooks read existing_email. The Stripe, Whop, GoHighLevel payment, ClickFunnels, PayPal, Typeform and Calendly connections do not. On GoHighLevel, send it through a workflow Custom Webhook action pointed at a receiving webhook.

The link covers the delivery that carried existing_email. A renewal sent later with only the paid email lands on the same person when the paid email is already linked to them as a second email, which is the case after a successful link. If the paid email is not linked to anyone, the renewal lands on the paid email, so send existing_email on renewals too.

More than one earlier email

If the buyer used several emails before (one to become a lead, another to book), list them all in existing_email, either as one string separated by commas, semicolons or spaces, or as a list:

{ "email": "[email protected]", "existing_email": "[email protected], [email protected]" }
{ "email": "[email protected]", "existing_email": ["[email protected]", "[email protected]"] }

We keep up to 10 emails. Duplicates and the paid email itself are removed first, so they do not use up a place.

Every listed email that already belongs to someone on your site becomes the same person as the buyer, so their visits, leads and purchases count once and a search by any of the emails finds them.

An email nobody has used yet is kept on the buyer, so a search finds the buyer by it, and we keep looking for 24 hours as described above.

An entry that is not a valid email is dropped and named in the delivery receipt. If every entry is invalid, the delivery is ignored with invalid_existing_email.

Each merge made this way shows under Users > Possible matches > Linked automatically, where you can undo it. A pair you marked Not the same person, or one you undid, is never merged by a webhook.

Also fire to connected ad platforms

Each receiving webhook has an Also fire to connected ad platforms toggle, off by default. Turn it on and the events also go to Facebook, TikTok, GA4 and Google Ads, just like a native integration. Your analytics get them either way. Custom events work too: Call Booked reaches your ad platforms under that same name.

Send a custom event to Facebook as a Custom Conversion

Once a custom-named receiving webhook exists, its event name shows up in Facebook's Create custom conversion event dialog, under a Custom webhook events group. Pick it there and we create a Facebook Custom Conversion with that name, so Facebook can optimize and report on it. We store it as an OTHER-type conversion, so it is never mistaken for a Lead or a Purchase, and it fires once per event with no duplicates. Facebook only gets the event while that webhook's Also fire to connected ad platforms toggle is on. See the Facebook integration guide for the dialog.

Credit the ad that booked the call

Here is a common case. Someone clicks one ad and books a call. Days later they click a second ad. Then your team marks the call qualified in your CRM, and the CRM sends that stage to a receiving webhook that fires to ad platforms.

By default we send that stage with the person's latest click, which is the second ad. If you want the ad that produced the booking to get the credit instead, send its click id back.

  1. Create a sending webhook for Schedule (or Lead). Each delivery carries attribution.last_touch.click_id, the click id of the ad that drove the booking. See the payload.
  2. Store that value on the contact in your CRM.
  3. When you send the later stage, put the stored value in a field named click_id.
{ "email": "[email protected]", "click_id": "IwAR_sample_fbclid" }

tm_click_id works the same way. A field named fbclid or gclid does not pick the click. Those only help us find the visitor, as before.

What happens next:

  • We find the click. It must be one of this person's own ad clicks from the last 90 days. That click goes to the ad platform it came from: a Facebook click to Facebook, a Google click to Google Ads, a TikTok click to TikTok. Other platforms still get the person's latest click.
  • We do not find it. For example, the click is older than 90 days, or it belongs to someone else. The event goes out with the latest click, exactly as before.
  • You send no click id. Same thing: the latest click, exactly as before.

The reply to your webhook says which one happened in click_id_status:

  • matched - we found the click, and it is the one used on any ad platform send for this event.
  • not_matched - you sent a click id, but we did not find it, so the latest click went out.
  • not_checked - there was nothing to check. You sent no click_id or tm_click_id (a fbclid or gclid on its own counts as none), Also fire to connected ad platforms is off, your site is in cookieless mode, or we had no person to check it against.

Only receiving webhooks pick a click from click_id. The GoHighLevel payment route, ClickFunnels, Stripe, Calendly, Typeform and the other built-in receivers do not. GoHighLevel users can send it from a workflow Custom Webhook to a receiving webhook, the same way they send existing_email.

We control which click we send. The ad platform decides what it credits. It still runs its own attribution, and it may still credit a later click that it saw itself.

The buyer's IP address and browser

A webhook comes from a server (your CRM, Zapier, your payment tool), not from the buyer's browser, so the IP address and browser on the request belong to that server. Facebook drops a conversion that claims a server is the buyer's browser, so we never send them.

An IP address or user agent field in your payload is not used for matching either. It is kept as an event property like any other field you send.

Instead, we send the buyer's own device. When the webhook is matched to a person by email or visitor id, we send the IP address and browser from that person's most recent visit to your site, as long as it was in the last 7 days. Their Facebook click id and browser id go along too when we have them, unless you sent a click id back, see Credit the ad that booked the call. There is nothing to set up: keep the tracker on your site and send the email.

If the person never visited, or their last visit was more than 7 days ago, we send no IP address at all rather than a wrong one. The email and phone still match them.

Event ID sent to ad platforms

TrueMetriks creates its own event ID (the event_id Facebook sees) for every event it sends to an ad platform. Your order_id is never used as the event ID.

So a Lead and a Purchase from the same buyer always reach Facebook as two separate events, each with its own ID. They do not need to share an order_id, and they do not need different ones.

A Lead does not need an order_id at all. order_id is for Purchases: it tells two orders apart and lets a refund find its sale.

Subscription renewals

A Purchase webhook can tell a new sale from a renewal of a subscription or payment plan. Click the pencil Edit webhook button on the webhook and pick an option under Subscription renewals. The option only shows on Purchase webhooks, and you can change it at any time.

  • Read it from the payload (the default). The payment is a renewal when the payload has purchase_type: "renewal", is_renewal: true ("true", 1 and "yes" count too), billing_reason: "subscription_cycle", or a "payment_number" above 1.
  • Every purchase on this URL is a renewal. For tools that cannot add a field: point the automation that runs on subscription payments at its own webhook with this option.
  • Every purchase on this URL is a first purchase. Every sale on this URL is a new sale, whatever the payload says.

A forced option always wins over the payload.

In the default mode we read these fields anywhere in the payload, nested ones included. Names can be snake_case or camelCase (is_renewal or isRenewal) in any letter case, and values are not case-sensitive. A name with spaces, like a CRM contact field called "Payment Number", is ignored. Fields you map yourself, such as in customData, win over the same field elsewhere in the payload. purchase_type: "new" or is_renewal: false marks a payment as a new sale.

When one part of the payload has both a renewal signal and a new-sale signal, the renewal wins. A label in the fields you map yourself still decides first, whatever the rest of the payload says.

Send subscription_id too if you have it. It links a subscriber's payments together.

When a payload carries a subscription_id and none of the other fields, the first paid payment we see for that subscription is the new sale and every later one is a renewal. A $0 or valueless Purchase is never counted as that first payment, so it stays unlabelled unless a forced option or a payload field labels it.

Also send order_id and value. The order_id stops a retried first payment from being counted as a renewal.

With a subscription_id, TrueMetriks remembers the first paid payment it saw for that subscription on this webhook URL. Later renewals are credited to the channel that won that first payment, see How are subscription renewals credited?

A renewal of a subscription whose first payment arrived before this feature, or never came through this URL, is credited on its own date.

A payload with none of these fields is recorded as a sale, exactly as before.

{
  "email": "[email protected]",
  "value": 77,
  "currency": "USD",
  "order_id": "inv_1042",
  "purchase_type": "renewal",
  "subscription_id": "sub_381"
}

With Also fire to connected ad platforms on, a first purchase always goes to your ad platforms as a Purchase. Renewals follow the site's setting on the Subscription renewals tile under Settings > Integrations: a custom event (named Renewal unless you change it), a Purchase, or nothing.

Refunds

A refund takes the refunded amount off the sale it belongs to. The sale keeps its date, channel and ad, so revenue, ROAS and profit go down on the day of the sale. See Refunds on the Revenue page.

There are two ways to send refunds by webhook.

A Refund webhook. Create a receiving webhook with the event type Refund and point your tool's refund automation at it. Every delivery on this URL is read as a refund.

A Purchase webhook that also gets refunds. Many tools send sales and refunds to the same URL. A Purchase webhook records a delivery as a refund, never as a new sale, when the payload says it is one:

  • an event, event_type, event_name, type, action or topic field that contains refund or chargeback, for example "type": "order.refunded";
  • transaction_type set to refund or partial_refund;
  • status, payment_status, financial_status or billing_status set to refunded or partially_refunded;
  • refunded or is_refunded set to true.

A refund_amount field on its own does not make a delivery a refund. Some tools send it with every sale as a running total.

Lead and Schedule webhooks record a refund only when the payload is a payment (for example type: payment) that says it was refunded; custom-event webhooks do not.

The order ID must be the original sale's

order_id is required, and it must be the order ID of the original sale, exactly as that sale reached TrueMetriks. That is how the refund finds its sale. Use the same field your sale automation sends as order_id, not the refund's own ID.

Field Required What it holds
order_id Required The original sale's order ID, exactly as the sale sent it. original_order_id or parent_order_id win when present.
refund_amount Recommended How much was refunded, as a positive number. amount_refunded, value and amount are read too. A minus sign is ignored.
refund_id Recommended The refund's own ID. Two partial refunds of one order both count, and a retried delivery counts once.
status Optional "status": "refunded" (or payment_status / financial_status set to refunded) marks a full refund. The whole sale comes off, whatever the amount says.
refunded Optional "refunded": true marks a full refund only when no amount is sent. With a refund_amount, it is a partial refund of that amount.
currency Optional The refund's currency. It is taken to be the sale's currency.
email Optional The buyer's email.

A delivery with no amount is recorded only when it says the whole order was refunded.

{
  "type": "refund",
  "order_id": "ORD-1042",
  "refund_id": "rf_381",
  "refund_amount": 25,
  "currency": "USD",
  "email": "[email protected]"
}

On a Refund webhook the type field is not needed.

What Recent deliveries says

Each refund shows in Recent deliveries as a line like "Refund - $25.00 for order ORD-1042", with one of these:

  • Matched to a sale - the refund found its sale and has been taken off it.
  • Waiting to match - TrueMetriks has the refund and is matching it to its sale. A match usually shows within a few minutes. If the sale has not arrived yet, TrueMetriks tries again after 1 hour and after 24 hours before it shows "No matching sale found".
  • No matching sale found - no sale with this order ID exists on this site, so the refund changes nothing. Check that order_id holds the original sale's order ID and that the sale itself reached TrueMetriks. A later refund for the same order is tried again.
  • Refund without an order ID - not recorded - add order_id to the payload.
  • Refund without an amount - not recorded - add refund_amount, or mark the order as fully refunded.

A refund larger than its sale only takes the sale down to zero.

A sale brought in through an import already had its refunds taken off, so a later refund for it changes nothing.

Refunds never go to your ad platforms. A Refund webhook has no Also fire to connected ad platforms toggle, and a refund arriving on a Purchase webhook is not sent either, even when that toggle is on.

Duplicate protection

We count each conversion once, even when two tools report it:

  • Leads, Schedules and custom events: the same email and event type counts once per day, across every source. A webhook and a native integration (say Typeform) reporting the same lead will not double-count.
  • Purchases are checked on email, order and amount instead, so two genuinely different orders on the same day both count.
  • Refunds are checked on the refund ID and amount, so a retried delivery counts once and a second partial refund still counts.

If a native integration already reports the same event type for this site, the webhook shows an amber warning as a reminder.

Recent deliveries

Every receiving webhook keeps a Recent deliveries log: the last 25 receipts, 5 per page. Each one shows what happened (accepted, deduped, parse error, oversized or ignored) plus a preview of the payload, so you can see exactly what arrived. A delivery that carried existing_email also says whether it was linked, is still waiting (up to 24 hours), or could not find that email.

Rotating or removing a webhook

There is no regenerate button, on purpose. To change a URL, delete the webhook and create a new one, which gets a new URL. Deleting one stops its URL working straight away. Payloads over 256 KB are rejected.

Send webhooks

Push conversions out of TrueMetriks to any URL - a CRM, GoHighLevel, or your own backend. Every Lead, Schedule and Purchase goes to your URL with the person's first and last touch, number of visits and paid channel attached. Leads reach GoHighLevel with the whole journey on them.

Step 1 - Create a sending webhook

Switch to the Send webhooks tab and click Add sending webhook.

Send webhooks 2 webhooks, 1 paused

Push conversions OUT of TrueMetriks. Every event is sent to your URL enriched with the person's first and last touch, sessions and paid channel.

GoHighLevel contacts active LeadSchedule

Webhook URL - we send events here

https://services.leadconnectorhq.com/hooks/aBcD1234
Recent deliveries (2)
Today 14:33:29 delivered Lead - [email protected], attempt 1 212 ms payload
Today 09:13:56 delivered Lead - [email protected], attempt 1 188 ms payload
Backend CRM sync paused Purchase
⚠ Paused automatically after 20 consecutive failures. Last error: 503 Service Unavailable. Fix the receiver, then unpause.
On the Send webhooks tab, click Add sending webhook. A dead URL auto-pauses and shows an Unpause button once you have fixed the receiver.

Fill in the dialog:

  • Name - a label for you (for example "GoHighLevel contacts").
  • Webhook URL - where we POST the payload. Must be https.
  • Send this event - pick ONE event from the dropdown: Lead, Schedule, Purchase, or one of your custom events (your Facebook Custom Conversions and custom-named receiving webhooks).

One sending webhook sends one event. To send another event to the same place, create a second one.

Click Create webhook.

Add sending webhook

Name

e.g. GoHighLevel contacts

Webhook URL

https://your-tool.com/webhook

Must be https. We POST a JSON payload to this URL for every matching event.

Send this event

Lead

Lead, Schedule, Purchase, or one of your custom events (your Facebook Custom Conversions and custom-named receiving webhooks).

Name it, paste your https URL, pick the one event to send, then click Create webhook.

Step 2 - Copy the signing secret

We show a signing secret once, right after you create the webhook. Copy it now, you will not see it again.

Sending webhook created

Every webhook we send is signed with this secret so your receiver can verify it came from TrueMetriks. Signature verification is optional.

Signing secret

whs_9d4e2a7c1f60b83e5a2d9c47f1b0e6a3

⚠  Copy it now - you will not see this secret again.

The signing secret shows once. Copy it now to verify the X-TrueMetriks-Signature header on each delivery.

Every delivery is signed so your receiver can check it came from us. The signature rides in an X-TrueMetriks-Signature: t=<unix>,v1=<hmac-sha256> header, built from the request body and your signing secret. Checking it is optional - receivers that do not check signatures (GoHighLevel inbound webhook triggers, for example) can ignore the header.

Step 3 - Know the timing

A delivery fires about 75 seconds after the event arrives. The wait is on purpose: identity and attribution settle first, so the payload carries the full journey. To test the wiring without waiting, click Send test and a sample payload arrives in about 15 to 30 seconds.

The test uses this webhook's real event name (Call Booked, not a generic Test), so your receiver sees exactly what a live delivery looks like. It is still marked with "test": true at the top level (and event.properties.test: true) so nothing downstream counts it as a real conversion, and in the Recent deliveries log the row reads Test: Call Booked. On a test send contact is null and attribution is sample data.

The payload

Every delivery is a JSON POST. event.type is Lead, Schedule or Purchase for standard events, and Custom for your own, so your receiver can branch on it:

{
  "api_version": "2026-07-09",
  "webhook": { "destination_id": "wdst_...", "attempt": 1, "sent_at": "2026-07-11T10:17:27.718Z" },
  "site": { "id": 1, "domain": "example.com" },
  "event": { "type": "Purchase", "name": "Purchase", "id": "evt_...", "time": "...", "value": 49.99, "currency": "USD", "source": "webhook", "properties": {} },
  "contact": { "email": "[email protected]", "phone": null, "first_name": "Jane", "last_name": null },
  "attribution": {
    "first_touch": {
      "source": "google", "medium": "cpc", "campaign": "brand-search", "term": "brand-exact", "content": "headline-a",
      "channel": "Paid Search", "referrer": "https://www.google.com/", "landing_url": "example.com/landing",
      "campaign_name": "brand-search", "adset_name": "brand-exact", "ad_name": "headline-a",
      "campaign_id": null, "adset_id": null, "ad_id": null,
      "click_id": "Cj0KCQiA_sample_gclid"
    },
    "last_touch": {
      "source": "facebook", "medium": "paid", "campaign": "retargeting", "term": "120210000000000001", "content": "video-testimonial-v3",
      "channel": "Paid Social", "referrer": "https://facebook.com/", "landing_url": "example.com/offer",
      "campaign_name": "retargeting", "adset_name": "Warm audience - 30d", "ad_name": "video-testimonial-v3",
      "campaign_id": null, "adset_id": "120210000000000001", "ad_id": "120210000000000002",
      "click_id": "IwAR_sample_fbclid"
    },
    "touches": 7, "sessions": 3, "days_to_convert": 7, "paid": true, "paid_channel": "Paid Social"
  }
}

On real events contact carries the person's actual email, phone, and name, and attribution their real journey. On test sends contact is null and attribution is sample data.

A Purchase from a subscription also carries purchase_type (new or renewal) in event.properties, subscription_id when the source sends one, and subscription_started_at (Unix seconds) when the subscription's start is known. A one-time sale has none of them.

Which campaign, which ad set, which ad

Each touch answers that three times over, so you can map it whichever way your CRM wants:

  • campaign_name, adset_name, ad_name are the readable answer. Use these. They are the same names the TrueMetriks dashboard shows for that visit.
  • campaign_id, adset_id, ad_id are the platform's own IDs for the same three things, for joining back to Facebook, Google or TikTok. null when the visit did not carry one.
  • source, medium, campaign, term, content are the raw UTM parameters exactly as they arrived, nothing resolved or cleaned. Use these if you tag with your own convention and would rather map it yourself.

A *_name is null when nothing readable exists for that level - the ad platform sent only an ID and we have no connected account to look the name up in. The matching *_id is then your handle on it. We would rather tell you nothing than print an ID where a name belongs.

A custom event delivers the same shape, with event.type set to Custom and event.name set to your event name:

{
  "api_version": "2026-07-09",
  "webhook": { "destination_id": "wdst_...", "attempt": 1, "sent_at": "2026-07-17T10:17:27.718Z" },
  "site": { "id": 1, "domain": "example.com" },
  "event": { "type": "Custom", "name": "Call Booked", "id": "evt_...", "time": "...", "source": "webhook", "properties": {} },
  "contact": { "email": "[email protected]", "phone": null, "first_name": "Jane", "last_name": null },
  "attribution": {
    "first_touch": { "source": "google", "medium": "cpc", "campaign": "brand-search", "channel": "Paid Search", "campaign_name": "brand-search", "adset_name": "brand-exact", "ad_name": "headline-a", "click_id": "Cj0KCQiA_sample_gclid" },
    "last_touch": { "source": "facebook", "medium": "paid", "campaign": "retargeting", "channel": "Paid Social", "campaign_name": "retargeting", "adset_name": "Warm audience - 30d", "ad_name": "video-testimonial-v3", "click_id": "IwAR_sample_fbclid" },
    "touches": 4, "sessions": 2, "days_to_convert": 1, "paid": true, "paid_channel": "Paid Social"
  }
}

A test delivery of that same webhook looks identical but adds a top-level "test": true and event.properties.test: true, so your receiver can drop it.

The click id on each touch

Each touch also carries click_id. It is the ad click id that the touch's own visit URL carried, exactly as it arrived. We check in this order: fbclid, gclid, gbraid, wbraid, ttclid, and take the first one the URL carries.

It is null when that visit's URL carried no click id. It is also null when the person has no UTM-tagged visit, because a touch is a visit with a utm_source, so an ad with no UTM tags gives no click_id.

last_touch.click_id on a Schedule or Lead delivery is the click that drove the booking. You can send it back to us later, see Credit the ad that booked the call.

Reliability

  • Stable IDs, so you can drop repeats. Each delivery carries an X-TrueMetriks-Delivery: dlv_<id> header and an event.id field, so your receiver can spot a retry. The X-TrueMetriks-Event header carries the event name.
  • Automatic retries, spaced further apart each time, when a delivery fails.
  • Dead URLs pause themselves. A URL that keeps failing is paused for you. The card shows why, with an Unpause button once your receiver is fixed.
  • Recent deliveries shows every attempt (delivered, queued, sending or failed) with the HTTP code.

Frequently asked questions

Does TrueMetriks integrate with my CRM, email platform or other tool?

Yes, if the tool can send or receive a webhook, and nearly every CRM, email platform, form, booking and payment tool can. That covers HubSpot, Salesforce, Pipedrive, GoHighLevel, ActiveCampaign, Klaviyo, Zapier, Make, n8n and your own backend. A tool with no webhooks of its own can still connect through Zapier or Make.

How does TrueMetriks know which visitor a webhook conversion belongs to?

It tries the visitor id first, then a click id (fbclid, gclid, click_id or tm_click_id), then the email address, and stops at the first one that finds a real visit. For most sites the email is enough, because buyers type it on the page. If conversions keep arriving with no visit attached, add the visitor id from the _evid cookie in a hidden field.

Can I update an existing user via webhook?

Partly. Every delivery records a conversion, and when its email belongs to someone we already know, it lands on that existing user. Name and phone help ad platforms match them, and existing_email adds a second email, or several, to them. A webhook cannot change a person's email or the name shown in TrueMetriks, and there is no update-only delivery.

Can a webhook link a second email to someone who already exists?

Yes. Send existing_email next to email, with the email they booked or signed up with. The sale lands on that person and the paid email is added to their profile. If we do not know them yet, we keep looking for 24 hours and move the sale onto them when they appear.

Do I need API keys to receive webhooks?

No. Create a receiving webhook, copy its secret URL, and paste that URL into the sending tool. The URL is the only credential.

What payload format does a receiving webhook accept?

POST JSON (form-encoded also works). TrueMetriks reads a simple schema (email, phone, first_name, last_name, value, currency, order_id) and auto-maps most other or nested payloads by key, so most tools work with no payload configuration.

How does TrueMetriks stop the same conversion counting twice?

The same email and event type within one UTC day counts once, across every source, so a webhook and a native integration reporting the same lead do not double-count. Purchases dedup on email, order, and amount instead, so two genuinely different orders both count.

Can a webhook send the buyer's IP address and browser to Facebook?

Not from the payload. A webhook comes from a server, so its IP address and browser belong to that server, and Facebook drops a conversion that claims a server is the buyer's browser. An IP address or user agent field you send is kept as an event property and is not used for matching. Instead, when the webhook is matched to a person by email or visitor id, TrueMetriks sends the IP address and browser from that person's own most recent visit to your site, if it was in the last 7 days. Nothing to set up.

Does the order_id become the event ID sent to Facebook?

No. TrueMetriks creates its own event ID for every event it sends to an ad platform, so a Lead and a Purchase from the same buyer always reach Facebook as two separate events. They do not need to share an order_id, and they do not need different ones. A Lead does not need an order_id at all. order_id is for Purchases, to tell two orders apart and to let a refund find its sale.

Can a webhook send refunds?

Yes. Create a receiving webhook with the event type Refund, or send refunds to your Purchase webhook with a refund field such as type: refund. Each refund must carry the original sale's order ID as order_id. TrueMetriks takes the refunded amount off that sale, on the sale's date, and never sends a refund to your ad platforms.

Can a sending webhook include attribution?

Yes. Every sent payload carries the person's first and last touch, channel, number of visits, and days to convert, so a CRM like GoHighLevel receives the full journey with each conversion.

Does a sending webhook tell me which ad the conversion came from?

Yes. Each touch carries campaign_name, adset_name and ad_name, plus the platform's campaign_id, adset_id and ad_id, plus every raw UTM parameter including utm_term and utm_content. A name is null only when the visit carried an ID with no name to resolve it against.

Can I credit the ad that booked the call, not a later ad click?

Yes. Store attribution.last_touch.click_id from the Schedule or Lead sending webhook on the contact, then send it back as click_id with the later event to a receiving webhook that fires to ad platforms. If it is one of that person's own clicks from the last 90 days, that click goes to the ad platform it came from instead of their latest one: a Facebook click to Facebook, a Google click to Google Ads, a TikTok click to TikTok. Other platforms still get their latest click. The ad platform still runs its own attribution and may credit a later click it saw itself.

How do I verify a sent webhook came from TrueMetriks?

Each delivery is signed with an X-TrueMetriks-Signature header (t=,v1=) using the signing secret shown once at creation. Receivers that do not verify signatures can simply ignore it.

Can one sending webhook send more than one event?

No. A sending webhook sends exactly one event - Lead, Schedule, Purchase, or one of your custom events. To send another event to the same place, create a second sending webhook.

When does a sending webhook fire?

About 75 seconds after the event is ingested, so identity and attribution settle first. Send test delivers a sample payload within about 15 to 30 seconds.

Need help with this?

Reach us instantly on WhatsApp, or send us a message and we will get back to you. On workdays we usually respond in less than 24 hours.

or send us a message