Universal Webhook Mapper
Use Universal Webhook Mapper when a third-party tool pushes a fixed payload that cannot match the Inbound Leads API format.
It accepts inbound data only. It does not send Convertly events to another system.
Create a source
Section titled “Create a source”Webhook-source management is restricted to workspace Admins.
- Open Settings -> API -> Universal Webhooks.
- Create a source with a recognizable external-tool name.
- Configure optional Lead Defaults and New Lead Alert recipients.
- Copy the generated webhook URL.
- Add the URL to the sending tool.
The generated URL contains a source token. Treat the complete URL as a secret and never place it in a public page or screenshot.
Capture a sample
Section titled “Capture a sample”Send one representative test payload from the external tool. Before mapping exists, Convertly captures a redacted and shortened sample, writes a log, and creates no lead.
Avoid including unnecessary personal or sensitive information in the sample.
Map fields
Section titled “Map fields”Open Map Fields and map captured dot paths, for example contact.email or visitor.phone, to Convertly fields.
At least email or phone mapping is required. Available destinations include contact fields, approved source, stage, value, notes, owner, categories, custom fields, click identifiers, UTMs, landing page, referrer, and consent metadata.
Mapped payload values take priority. Enabled source defaults fill missing supported values.
New Lead Alerts
Section titled “New Lead Alerts”Select the users who should receive new-lead alerts from this source. An empty list sends no source-level new-lead alert. Assignment notification to a mapped or default owner remains separate.
Extra secret mode
Section titled “Extra secret mode”New sources can receive requests through the generated URL token. If the sender supports custom headers, enable the optional extra-secret mode and send the value through x-webhook-secret.
The secret is displayed only when created or regenerated. Store it securely and rotate it if exposed. Regenerating the webhook URL stops the previous URL from working.
Test and monitor
Section titled “Test and monitor”After saving mappings, send unique test contact data. Confirm the lead, defaults, source, ownership, campaign context, and duplicate behavior.
Review Settings -> API -> API Logs. Logs contain safe operational metadata and do not display raw URL tokens, extra secrets, or complete payloads.