Usercentrics Conversions Client¶
The Usercentrics conversions client is a server-side Google Tag Manager (sGTM) client template that receives offline conversion events from customer relationship management (CRM) and business systems (such as Salesforce or HubSpot) and routes them through your sGTM container. Use it to send form submission, post-purchase, or lifecycle stage events to analytics or ad platforms (Meta CAPI, Google Ads, LinkedIn, TikTok) without relying on a browser pixel.
The Usercentrics Conversions Client template is available to all sGTM customers on any plan.
This page covers what the template does and when to use it, then walks through setup end-to-end.
Use cases¶
Use this template to implement the following use cases:
Route Salesforce conversions to Meta CAPI. When a lead generated from a Meta ad converts offline (for example, closes a deal in Salesforce), Salesforce sends a webhook to the conversion client. The client maps the lead email and deal value to sGTM fields, and your Meta CAPI tag fires with the full event, attributing the conversion to the original ad without a browser pixel.
Send HubSpot lifecycle stage changes to Google Ads. Configure HubSpot to POST a webhook when a contact moves from marketing qualified lead (MQL) to Customer. The conversion client receives the event, maps the contact ID and stage to sGTM fields, and triggers a Google Ads conversion tag. Your smart bidding model stays updated with offline pipeline data.
Normalize events from multiple sources. Deploy one client instance for Salesforce and a separate instance for HubSpot, each configured with its own request path and field mappings. This keeps the mapping logic clean and makes it easy to debug events from each source independently.
Access raw CRM fields in tags. Enable Pass through all original fields and reference any field from the original payload in your tags with an Event Data variable pointed at that field's path. For example, an Event Data variable for timestamp gives you the originating event timestamp without adding it to the field mapping table.
How it works¶
Your CRM or business system sends an HTTP POST request to a path on your sGTM server. The conversions client claims that request, maps the incoming fields to sGTM's internal event format, and makes the event available to any tag in your container. You control which platforms receive the event through your existing tag and trigger configuration.
Prerequisites¶
The following are the prerequisites of using the conversions client:
- An active sGTM container hosted by Usercentrics
- Your sGTM server URL (e.g.,
https://metrics.yourdomain.com) - The ability to configure webhooks or HTTP calls in your CRM or business system
Setup at a glance¶
The following sections walk you through the steps of setting up, configuring, using and testing the conversions client. A short overview of the steps:
Configure and install the template¶
To configure and install the template, follow these steps:
- Download the usercentrics-conversions-client.tpl template file
- In your sGTM workspace, go to Templates > Client Templates > New.
- In the Template Editor, select the 3 dots menu in the top-right corner, click Import, select the downloaded .tpl file, and click Save.
- Go to Clients > New.
- Click Choose a client type to begin setup... and select Usercentrics Conversions Client as the client type.
- Configure the template fields (see the Configuration reference for all options).
- Save the client and publish your container.
Configuration reference¶
| Field | Description | Default value | Example |
|---|---|---|---|
| Priority | Built-in sGTM client setting, not specific to this template. Determines the order clients evaluate an incoming request — higher numbers run first, and the first client that claims the request handles it. | n/a — set by sGTM, not this template | 0 |
| Request path to claim | The exact request path this client claims. Requests on any other path are left for other clients to handle. | /crm-events | /crm-events |
| Require a shared-secret header | When enabled, the client validates a shared-secret header before processing the request. Offline senders aren't browsers, so a header secret helps keep the endpoint from accepting fraudulent or malicious events. | true | true |
| Auth header name | The HTTP header that carries the shared secret. Only used when Require a shared-secret header is enabled. | X-Api-Key | X-Api-Key |
| Expected auth header value | The secret the sender must provide to pass validation. Treat this as a credential. | (empty — you must set one) | sk_live_9f2a1b... |
| How to handle multiple records | Whether the client treats the payload as a single event or fans an array out into one event per item. | One event per array item | One event per array item |
| Path to the array in the body | Dot-notation path to the array of records in the request body, e.g. data.events. Leave blank if the request body itself is the array. Only used when How to handle multiple records is set to fan out an array. | (empty — body is treated as the array) | data.events |
| Event name path (optional) | Dot-notation path to a value in each record to use as the event name, e.g. eventType. Falls back to Default event name if blank or not found. | (empty) | eventType |
| Default event name | Fallback event name used when no event name path is set or matched. | offline_conversion | offline_conversion |
| Map source fields to standard GTM fields | Table mapping a source path in the incoming record to a standard GTM event field (e.g. value, currency, user_data.email_address, user_data.phone_number, user_id). Nested target fields are created automatically. | (empty — no mappings) | Deal.Amount → value |
| Pass through all original fields | When enabled, fields not listed in the mapping table are preserved on the event and accessible to your tags. When disabled, they're discarded. | true | true |
| Candidate IP parameter names | A priority list of field names to search for the originating IP address. The client searches the payload only (not headers), checks nested objects and arrays, and is case-insensitive. The first match, top to bottom, wins. | ip, ip_address, client_ip, original_ip, remote_ip, x_forwarded_for | same as default |
| Use first hop of comma-separated values (X-Forwarded-For) | When a matched value is a chain like client, proxy1, proxy2, uses only the first address (the original client). Single IP values are unaffected. | true | true |
| Write IP to this event field | The event field the detected IP address is written to. ip_override is the standard field GA4, Google Ads, and Meta CAPI tags read for the user's IP — only change this if you have a specific downstream reason. | ip_override | ip_override |
| Success response body | The response body returned to the sender once all events are processed successfully. | {"success":true} | {"success":true} |
| Enable console logging (debug) | Logs internal processing steps to the console for troubleshooting. See Enable logging to verify the setup. | false | true (while debugging) |
Field mapping¶
Every CRM and business system structures its payload differently. The field mapping table enables you to translate incoming field names to standard GTM event fields without modifying the template.
To add a mapping:
- Click Add mapping in the field mapping table.
- Enter the Source path in payload: the dot-notation path to the field in your incoming payload (e.g.,
contact.email_address). - Enter the Standard GTM field: the GTM event field to map it to (e.g.,
user_data.email_address).
Common mappings:
| Incoming field (example) | Standard GTM field |
|---|---|
contact.email | user_data.email_address |
contact.phone | user_data.phone_number |
data.amount | value |
data.currency | currency |
event_type | event_name |
If Pass through all original fields is enabled, fields not listed in the mapping table are preserved on the event and accessible to your tags via an Event Data variable. Otherwise, they're discarded.
IP detection¶
The client checks each configured field, top to bottom, and writes the first match to the event field set in Write IP to this event field (ip_override by default). This lets downstream tags receive the original user IP address rather than the IP of the sending server. Matching is case-insensitive and searches nested objects and arrays in the request body — headers are not checked, so any value you want matched must be present in the payload.
Default fields checked (in order):
| Source | Type |
|---|---|
ip | Payload field |
ip_address | Payload field |
client_ip | Payload field |
original_ip | Payload field |
remote_ip | Payload field |
x_forwarded_for | Payload field |
You can add, remove, or reorder these entries in the template configuration — the first match, top to bottom, wins regardless of where it sits in the JSON. If none of the configured sources contain an IP address, no override is applied.
Send events from your CRM¶
Configure your CRM or business system to send an HTTP POST request to:
https://<your-sGTM-domain>/<request-path>
For example: https://metrics.yourdomain.com/crm-events
Request format:
- Method:
POST - Content-Type:
application/json - Body: your event payload (single JSON object or array, depending on your How to handle multiple records setting)
Example payload (single event):
{
"event_type": "purchase",
"event_id": "order-98231",
"contact": {
"email": "user@example.com",
"phone": "+49123456789"
},
"data": {
"amount": 149.00,
"currency": "EUR"
},
"timestamp": "2026-06-10T14:00:00Z"
}
With the field mappings from the example table, this event would arrive in your sGTM container with user_data.email_address, user_data.phone_number, value, and currency already populated.
Response codes¶
| Status | Meaning |
|---|---|
200 OK | Event received and processed successfully |
400 Bad Request | Payload couldn't be parsed (invalid JSON, empty event, or malformed array structure) |
401 Unauthorized | Authorization is enabled and the request didn't include a valid token |
405 Method Not Allowed | If the request method is not POST (ex. GET), the request is rejected |
When processing an array of events, the entire structure of the request is evaluated, so a single malformed event will cause the entire request to be rejected as a 400.
Test your setup¶
- Open your sGTM workspace and click Preview.
- Send a test POST request to your sGTM endpoint using a tool such as Postman or curl from your terminal.
- In the preview panel, confirm the request is claimed by the Usercentrics Conversions Client.
- Check the Event data tab to verify your field mappings applied correctly.
- Confirm the expected downstream tags fired.
To test error handling, send a request with an invalid JSON body and verify a 400 response is returned.
Best practices¶
Use one client per data source¶
Because every CRM structures its payload differently, the recommended pattern is to use one client template instance per data source. Separate instances keep configuration readable and easier to debug.
Verify consent before the event is sent¶
The conversion client doesn't enforce consent on its own. Consent for offline events should be verified upstream in your CRM or business system before the event is sent. If you pass a consent signal in the payload, you can map it to a field and reference it in your tag triggers.
Enable logging to verify the setup¶
Logging is not enabled by default, but can be enabled under Response & debugging. The console log output is visible in GTM preview mode and in your container logs, which helps you verify field mappings and trace event flow during setup.