How It WorksPricingIntegrationsAffiliatesDocsBlog
Log inGet Started

Connect your data source.

Configure webhooks from your CRM, landing page builder, or custom application to send lead data to DealOracle.

Get Webhook URL

From your DealOracle dashboard

Configure Source

Set up webhook in your CRM

Send Test Event

Verify data is received

Your Webhook URL

Your unique webhook URL is available in the DealOracle dashboard under Settings → Integrations → Webhook.

https://your-project.supabase.co/functions/v1/client-api/clients/{your-client-id}/leads

Your webhook URL is unique to your account. You'll also need to include your API key as an X-API-Key header.

Payload Format

Example Webhook Payload
{
  "first_name": "John",
  "last_name": "Doe",
  "email": "[email protected]",
  "phone": "+15551234567",
  "status": "new",
  "lead_source": "facebook",
  "utm_source": "facebook",
  "utm_campaign": "summer_sale",
  "fbclid": "IwAR3abc...",
  "gclid": "CjwKCAjw...",
  "fb_adset_id": "12345678",
  "fb_adset_name": "Lookalike Audience"
}

Lead Data Fields

emailrequired

Lead's email address

phone

Phone number (any format)

first_name

Lead's first name

last_name

Lead's last name

status

Current lead status (e.g., new, qualified, converted)

lead_source

Where the lead came from (e.g., facebook, google)

Tracking Fields

fbclid

Facebook Click ID, captured from URL parameter

gclid

Google Click ID, captured from URL parameter

ttclid

TikTok Click ID, captured from URL parameter

utm_source

UTM source parameter for campaign attribution

utm_campaign

UTM campaign name

fb_adset_id

Facebook Ad Set ID for ad-level attribution

fb_adset_name

Facebook Ad Set name

ip_address

User's IP address for improved matching

Capturing UTM parameters on your forms

Most forms don't send UTM and click ID data by default, you need to add hidden fields. We wrote a step-by-step guide covering every major platform.

Read the UTM setup guide →

Multi-Step Forms & Deduplication

You don't need a separate endpoint to update a lead. The same ingest URL handles both creating new leads and updating existing ones automatically.

How it works

When a lead is submitted, DealOracle checks if a lead with the same email or phone number already exists in your account. If it does, the new data is merged onto the existing record instead of creating a duplicate.

Example: 2-step form

Step 1, Name & Phone

POST /clients/{id}/leads

{
  "first_name": "Jane",
  "phone": "555-0100"
}

→ { "inserted": true, "id": "a1b2..." }

Step 2, Email

POST /clients/{id}/leads

{
  "phone": "555-0100",
  "email": "[email protected]"
}

→ { "merged": true, "id": "a1b2..." }

Merge rules

  • Mutable fields (name, address, lead source), always overwritten with the latest value
  • Attribution fields (gclid, fbclid, UTMs), first-write-wins, only backfilled if empty
  • Status, only updated if the new value is not "new" (won't downgrade a lead that's been progressed)

This works with any platform, CRMs, form builders, Zapier, or direct API calls. Just POST to the same ingest URL each time with whatever fields you have.

Updating Existing Leads

You have multiple options for updating a lead, you don't always need a lead ID. Choose the method that fits the data you have available.

PATCH/clients/{id}/leads

Update by phone, no lead ID needed. Send the phone number in the body as a lookup key, along with the fields you want to change. Finds the most recent matching lead in the client account.

PATCH /clients/{client_id}/leads

{
  "phone": "555-0100",
  "status": "contacted"
}
POST/clients/{id}/leads/{leadId}

Update by lead ID. Use this when you already have the lead's UUID, e.g. from a previous search, Zapier lookup, or the response from creating a lead.

POST /clients/{client_id}/leads/{lead_id}

{
  "status": "sold",
  "value": 25000
}

Which should I use?

  • From a CRM or call tracking: Use PATCH with phone, you typically have the number but not the lead ID
  • From Zapier after a lookup step: Use POST with the lead ID returned by the "Find Lead" search action
  • Just want to create or merge: Use POST to /leads (without a lead ID), it auto-deduplicates by phone or email

All update methods trigger conversion tracking automatically when the status changes, Facebook CAPI, Google Ads, TikTok, and Microsoft events fire based on your disposition settings.

Platform Setup Guides

LeadConnector Setup

Navigate to Automations

Go to Automation → Workflows in your LeadConnector account.

Create or Edit a Workflow

Create a new workflow or edit an existing one that triggers on new leads or status changes.

Add Webhook Action

Add an action step and select "Webhook" from the list.

Configure the Webhook

URL: Paste your DealOracle webhook URL

Method: POST

Headers: Content-Type: application/json

Map Fields

Use GHL's custom values to map fields:

{
  "email": "{{contact.email}}",
  "phone": "{{contact.phone}}",
  "first_name": "{{contact.first_name}}",
  "last_name": "{{contact.last_name}}",
  "fbclid": "{{contact.fbc}}",
  "gclid": "{{contact.gclid}}",
  "utm_source": "{{contact.utm_source}}",
  "utm_campaign": "{{contact.utm_campaign}}"
}

Capture Click IDs & UTMs

Make sure your landing pages capture fbclid, gclid, ttclid, and UTM parameters into contact custom fields.

Testing Your Webhook

Use the Test Panel in Dashboard

Go to Settings → Integrations → Webhook and use the "Send Test Event" button to verify your setup.

Check Event Logs

View received webhooks in real-time under the Event Streams page. Each event shows the payload received and processing status.

Verify in Ad Platforms

After sending a test event, check Facebook Events Manager, Google Ads, or TikTok Events Manager to confirm the event was received.

View API Reference for programmatic integration

Need help with setup?

Our team is here to help you configure webhooks for your specific platform.

Contact Support