Lead Webhooks allow MetaLocator to securely send lead submissions in near-real time to external systems such as CRMs, marketing automation platforms, internal APIs, middleware platforms, and custom applications.
This feature is commonly used by Enterprise customers who need to:
Push leads into internal business systems immediately after submission
Integrate MetaLocator with platforms such as Salesforce, HubSpot, Zapier, Make, or custom APIs
Trigger downstream workflows or automations
Configuring a Lead Webhook
Login to MetaLocator
Click Interfaces
Navigate to the Interface that will be generating leads and click Edit
Click the Lead Generation Tab
Provide your Webhook URL in the Lead Webhook URL setting.
Configuring Lead Webhook Authentication
With "Shared Token" authentication enabled, MetaLocator signs outbound webhook requests using a secure shared secret (the token). Your receiving application can then verify the signature using the same Shared Token to ensure the request has not been modified and was sent by a trusted source.
These instructions explain how to:
Create a new Shared Token
Configure Lead Webhook Authentication
Assign the Shared Token to your interface
Securely validate incoming webhook requests
First, create a new Shared Token as follows:
Login to MetaLocator
Click "My User Profile"
Click "API Keys"
Click New
Choose "Shared Token"
Provide a name for the token and click Save
Copy the provided token and save in a safe place for use in your integration.
Click Interfaces
Navigate to the Interface that will be generating leads and click Edit
Click the Lead Generation Tab
Choose Signature Verification (Shared Token) for the "Lead Webhook Authentication" setting
Choose the Shared Token created in step 6 for the Shared Token setting just below the "Lead Webhook Authentication" setting
Save the Interface
The webhook payload now includes special headers which allow your receiving application to verify that the webhook actually came from MetaLocator. Details on this process are documented here.
Adding Custom Header Tokens to Lead Webhooks
Some webhook receiving systems require authentication using a custom HTTP header, such as X-Webhook-Token, X-Customer-Secret, or another header name defined by your CRM, middleware platform, or internal API.
MetaLocator supports Custom Secure Tokens for this purpose. When configured, MetaLocator will include the selected custom header and token value as an additional HTTP header on outbound lead webhook requests.
Custom Header Tokens can be used in addition to the standard Shared Token signature verification method.
Creating a Custom Secure Token
Login to MetaLocator.
Click My User Profile.
Click API Keys.
Click New.
Choose Shared Token.
Provide a unique descriptive name for the token.
Under Token Type, choose Custom Secure Token.
Enter the custom HTTP header name required by your receiving system, for example:
X-My-Webhook-TokenEnter the custom token value provided by your receiving system, or create a secure random value and configure that same value in your receiving system.
Click Save.
Custom token values are stored securely and cannot be retrieved or displayed after saving. Be sure to store the value in your own secure system before saving.
Adding Custom Header Tokens to an Interface
After creating the Custom Secure Token:
Click Interfaces.
Navigate to the Interface that will be generating leads and click Edit.
Click the Lead Generation tab.
Confirm that your Lead Webhook URL is configured.
Locate the Custom Header Tokens setting.
Select one or more Custom Header Tokens to include with outbound webhook requests.
Save the Interface.
When a lead is submitted, MetaLocator will send the webhook request to your configured Lead Webhook URL and include the selected custom header token values as HTTP headers.
For example, if you create a Custom Secure Token using the header name:
X-My-Webhook-Token
MetaLocator will include that header in the outbound webhook request.
Using Custom Header Tokens with Signature Verification
Custom Header Tokens are additive. This means they can be used alongside the standard Signature Verification (Shared Token) authentication option.
For higher-security integrations, you may choose to use both:
Signature Verification (Shared Token) to verify that the webhook payload was sent by MetaLocator and was not modified in transit.
Custom Header Tokens to satisfy authentication requirements from your receiving system.
Important Notes
Custom header names must use valid HTTP header characters.
The following header names are reserved and cannot be used:
X-MetaLocator-Webhook-SignatureX-MetaLocator-Webhook-Signature-TimestampHost
Custom Secure Token values are stored securely and are not displayed after creation. If a token value is lost or needs to be changed, create a new Custom Secure Token and update the Interface to use the new token.
Error Handling in Lead Webhooks
The HTTP Response Code and HTTP Response Body will be stored along with the lead object. Your Webhook should respond with an appropriate HTTP status code indicating success, e.g. 200.
Retrying Webhooks
If a lead webhook fails to send, you can retry the webhook from the Leads screen. Retrying a webhook sends the original webhook payload again without re-sending the lead notification or creating a duplicate lead. Read more here.
Error Reports
When a webhook failure is detected, MetaLocator will email the account owner an error report. Error reports are generated in the following scenarios:
HTTP response codes of 300 or greater will trigger an error report.
Unresponsive endpoints that timeout
Endpoints with an invalid SSL certificate
Unresolved DNS of the Webhook URL
Network connectivity issues.
Endpoints that fail to establish an HTTP connection will be stored with an "999" HTTP status code and any error messages will be stored in the Webhook Response field.
A sample Webhook error email can be found below:
