Discover. Learn. Grow.

TABLE OF CONTENTS

• Introduction
• Incoming Webhooks compared with the Single Record API
• How to Setup
• Calling the Webhook
  • Request method and endpoint
  • Authentication
  • Parameters
  • Query string requests
• Fields and validation
• Import types
  • Accounts
  • Contacts
  • Surveys
  • Multi-Object
  • Account Aliases
  • Signals
  • External Responses
• HTTP Responses
• Troubleshooting
  • The request is not authenticated
  • A field is not populated
  • The request fails validation
  • A Survey was not sent

Introduction

Incoming Webhooks allow another system to send one record at a time to CustomerGauge without implementing OAuth2. Depending on the Inbound Mapping used to generate the webhook, a request can:

• Create or update an Account;
• Create or update a Contact;
• Create an Account Alias;
• Send a Survey invitation;
• Create or update an Account and Contact while sending a Survey invitation;
• Create a Signal from unstructured customer feedback; or
• Import a Survey response collected in another system.

Each webhook is connected to one Inbound Mapping. The mapping determines the import type, the CustomerGauge fields that can be populated, and the Field Headings that must be used in the request.

Incoming Webhooks compared with the Single Record API

Use the Single Record API when your application can implement OAuth2 and manage access tokens. Use an Incoming Webhook when the source system supports a simple authenticated webhook call.

How to Setup

To be able to generate a webhook that can trigger survey invitations you will need an Inbound Mapping.

• Navigate to Data → Rest APIs → Inbound Mapping.
• Under Actions, click on the 3 dots and then Generate Webhook.
  
  
  
  
• Click on Save.
  
  
  
  
• A webhook will be generated and all the necessary information will be shown.
  
  

If you need to check the webhook information and credentials at a later stage, you can do so by following these instructions:

• Navigate to Data → Integrations → Webhooks.
• Under Actions, click on the 3 dots and then View. You can also Deactivate or Delete the webhook here as well.

Calling the Webhook

When calling the webhook each inbound mapping type has a unique interaction:

Request method and endpoint

Send an HTTP PUT request to the Webhook URL generated by CustomerGauge:

PUT {{webhook_url}}

A generated URL resembles the following example:

https://hooks.eu.customergauge.com/xxxxxxxxxxxx

Authentication

Incoming Webhooks use Basic Authentication. Send the generated Username and Password in the Authorization header:

Authorization: Basic Base64.Encode("{{username}}:{{password}}")

Most HTTP clients create this header automatically. For example, cURL's --user option encodes the credentials for you:

curl --location --request PUT '{{webhook_url}}' \ --user '{{username}}:{{password}}' \ --header 'Content-Type: application/json' \ --data-raw '{ "Email": "joe.doe@example.com" }'

Keep the Webhook URL, Username, and Password secure. Do not expose them in browser-side code or commit them to source control.

Parameters

Each JSON key must exactly match a Field Heading in the Inbound Mapping used to generate the webhook. Field Headings are case-sensitive and can contain spaces.

For example, if the mapping contains the headings Account Name, First Name, Last Name, and Email, send:

{  "Account Name": "ACME",  "First Name": "Joe",  "Last Name": "Doe",  "Email": "joe.doe@example.com" }

Do not wrap the fields in record and do not send a configuration value. Those parameters belong to the Single Record API. The generated webhook URL already identifies the Inbound Mapping.

Query string requests

Parameters can also be sent in the query string. URL-encode field headings and values where required:

curl --location --request PUT \  '{{webhook_url}}?Email=joe.doe%40example.com&Touchpoint=Support' \  --user '{{username}}:{{password}}'

JSON is recommended for requests with several fields, or characters that would otherwise need URL encoding.

Fields and validation

• The request can populate only fields included in the Inbound Mapping.
• The import type's required fields must be included in the mapping and request.
• Additional fields can be made mandatory under Settings → System Admin → System Settings → Field Settings.
• Email fields must contain a valid email address.
• Phone fields must contain a valid phone number. Numbers, spaces, parentheses, dashes, and the plus sign are accepted. Numbers only are recommended.
• Date values must use YYYY-MM-DD or YYYY-MM-DD HH:MM:SS.
• Values must follow the field type, maximum length, and any Restrict new values on upload rule configured in Field Settings.
• A Touchpoint value is accepted only when that Touchpoint already exists in CustomerGauge.

Import types

Accounts

Use this import type to: Create a new Account or update an existing Account without creating a Contact or sending a Survey.

Required field: Account Name.

CustomerGauge uses Account Name as the Account identifier. If the Account does not exist, it is created. If it already exists, the mapped Account fields supplied in the request are updated.

Example request:

curl --location --request PUT '{{webhook_url}}' \  --user '{{username}}:{{password}}' \  --header 'Content-Type: application/json' \  --data-raw '{    "Account Name": "ACME",    "Account Display Name": "ACME Corporation",    "Account Manager": "John Doe",    "Account Manager Email": "john.doe@example.com"  }'

Contacts

Use this import type to: Create a new Contact or update an existing Contact without sending a Survey.

Required field: Email or Phone.

CustomerGauge uses the Email address or Phone number to identify the Contact. Include Account Name when the Contact should be associated with an Account.

Example request:

curl --location --request PUT '{{webhook_url}}' \  --user '{{username}}:{{password}}' \  --header 'Content-Type: application/json' \  --data-raw '{    "Account Name": "ACME",    "First Name": "Joe",    "Last Name": "Doe",    "Email": "joe.doe@example.com",    "Job Title": "Operations Manager",    "Country": "NL"  }'

For a Contact identified by phone, replace Email with the Phone heading configured in the mapping:

{  "Account Name": "ACME",  "First Name": "Joe",  "Last Name": "Doe",  "Phone": "+31 20 123 4567" }

Surveys

Use this import type to: Create a Survey invitation for a Contact already known to CustomerGauge.

Required field: Contact Reference, using Email or Phone.

CustomerGauge looks up the Contact by Email or Phone and creates a Survey record. Account and Contact fields can be populated automatically from the existing Contact when they are not supplied in the request. The invitation is then processed according to the applicable Campaign Suite rules.

Example request:

curl --location --request PUT '{{webhook_url}}' \  --user '{{username}}:{{password}}' \  --header 'Content-Type: application/json' \  --data-raw '{    "Email": "joe.doe@example.com",    "Touchpoint": "Support",    "Order Number": "TICKET-10243",    "Sent Date": "2026-08-27 10:30:00"  }'

Survey imports are subject to the platform and Campaign duplication rules. A valid import may therefore be prevented from sending another invitation when it is considered a duplicate.

Multi-Object

Use this import type to: Create or update Account and Contact data while also creating a Survey invitation.

Required field: Email or Phone.

Use Multi-Object when the source event contains all the information needed to maintain the Account and Contact and send the Survey in one request. CustomerGauge creates or updates the referenced Account and Contact, creates the Survey record, and processes the invitation according to the applicable Campaign Suite rules.

Example request:

curl --location --request PUT '{{webhook_url}}' \  --user '{{username}}:{{password}}' \  --header 'Content-Type: application/json' \  --data-raw '{    "Account Name": "ACME",    "Account Display Name": "ACME Corporation",    "First Name": "Joe",    "Last Name": "Doe",    "Email": "joe.doe@example.com",    "Touchpoint": "Support",    "Order Number": "TICKET-10243"  }'

Multi-Object Survey imports are subject to the platform and Campaign duplication rules.

Account Aliases

Use this import type to: Add an alternate name for an Account so supported import processes can recognize the same Account under another name.

Required fields: Account Name and Alias.

Account Name identifies the target Account. Alias contains the alternate value that may appear in another source system.

Example request:

curl --location --request PUT '{{webhook_url}}' \  --user '{{username}}:{{password}}' \  --header 'Content-Type: application/json' \  --data-raw '{    "Account Name": "ACME Corporation",    "Alias": "ACME NL"  }'

Account Aliases can be used by supported Contact, Survey, Activity, and Incoming Webhook import processes. They are not used by Classical or Transactional Data imports.

Signals

Use this import type to: Turn unstructured customer feedback, such as an email chain, call transcript, meeting note, or support conversation, into a Signal response in CustomerGauge.

Required field: Source Content.

Signal analyzes the supplied Source Content and creates a response through its dedicated processing flow. This can trigger standard post-response processes such as Comment Translation, Workflow and Close the Loop alerts, Comment Analysis, and the Close the Loop Assistant.

Include available Account and Contact details so the Signal can be associated with the correct customer context. Make sure Source Content is valid JSON and escape quotation marks, line breaks, backslashes, and other characters where required.

Example request:

curl --location --request PUT '{{webhook_url}}' \  --user '{{username}}:{{password}}' \  --header 'Content-Type: application/json' \  --data-raw '{    "Account Name": "ACME",    "Email": "joe.doe@example.com",    "Touchpoint": "Account Management",    "Sent Date": "2026-08-27 09:00:00",    "Survey Completed Date": "2026-08-27 09:30:00",    "Source Content": "Account Manager: How has the onboarding been?\nCustomer: The team has been helpful, but access approvals took longer than expected.\nAccount Manager: Thank you. I will follow up with the implementation team."  }'

External Responses

Use this import type to: Import a Survey response that was collected in another system.

Required fields:

• Email or Phone;
• Sent Date; and
• Response Date. This is commonly mapped using the Survey Completed Date field.

Include the response fields you want to store, such as NPS Score, Comment, or other questions configured in the Inbound Mapping. External Responses are recorded in CustomerGauge but do not send a new Survey invitation.

Example request:

curl --location --request PUT '{{webhook_url}}' \  --user '{{username}}:{{password}}' \  --header 'Content-Type: application/json' \  --data-raw '{    "Account Name": "ACME",    "Email": "joe.doe@example.com",    "Touchpoint": "Support",    "Sent Date": "2026-08-26 15:00:00",    "Survey Completed Date": "2026-08-27 08:45:00",    "NPS Score": "6",    "Comment": "The issue was resolved, but it took longer than expected."  }'

HTTP Responses

Your integration should log the HTTP status and response body. For Survey and Multi-Object webhooks, also prevent the source event from being submitted repeatedly. CustomerGauge duplication rules may block duplicate invitations, but duplicate prevention should also be handled by the source integration.

Troubleshooting

The request is not authenticated

• Confirm that the request uses Basic Authentication, not a Bearer token.
• Use the Username and Password generated for this specific webhook.
• Confirm that the webhook has not been deactivated or deleted.

A field is not populated

• Confirm that the field is included in the Inbound Mapping.
• Confirm that the JSON key exactly matches the Field Heading, including spaces and capitalization.
• If the mapping was edited, update the source request to use the new Field Heading.

The request fails validation

• Confirm that all fields required for the import type are present.
• Check whether additional fields have been made mandatory in Field Settings.
• Validate the Email, Phone, Date, Number, and Text formats.
• Check whether Restrict new values on upload prevents the supplied value.
• For Touchpoint, confirm that the supplied value already exists in CustomerGauge.

A Survey was not sent

• Confirm that the Survey or Multi-Object import itself completed successfully.
• Check that the record matches an active Campaign and its filters.
• Check the platform and Campaign duplication rules.
• Confirm that the Contact has a valid destination for the Campaign's delivery channel.