Lead Cluster Webhook

A lead cluster refers to a group of leads matched based on key customer information such as phone numbers or emails. The webhook exports lead cluster details when created or updated in Dealer Studio to external systems. The webhook sends its details and its associated leads details, updates, assignments, and status changes, to the external system associated to the endpoint configured.

Create: when a lead cluster is first created, Dealer Studio POSTs the full payload below to webhook_api_url.

Update: when cluster data changes (contact details, vehicles of interest, status or assignee changes, test drive appointments, lead events, a lead moving to a different cluster, and similar), Dealer Studio POSTs the same JSON shape again to the same webhook_api_url. Treat create and update payloads identically on your side.

When a lead moves from one cluster to another, both clusters receive an update: the destination cluster’s payload now includes the lead, and the source cluster’s payload no longer does.

Schema version

Each cluster webhook notification is configured with schema_version v1, v2, or v3. Per-lead webhooks use a separate version set (v1–v4); cluster webhooks do not offer v4.

Version	When to use	Summary
v1	Existing integrations	Legacy envelope: `dealership_id`, `created` / `modified`, ADF-style `leads` (`item`, `prospect`, `comments`), `lead_events` with `user_name`.
v2	New integrations (baseline)	Show-aligned minimal payload: `dealership` `{ id, name }`, `created_at` / `updated_at`, `cars` (not `vehicles_of_interest`), slim `leads` (`message`, `fields`), `appointments`, `test_drives`, `lead_events` with `user: { id, name }`.
v3	Need lead supplier identity	Everything in v2, plus `provider: { id, name }` on each nested lead.

The field tables below describe the v1 contract unless noted. For v2 / v3, use cars instead of vehicles_of_interest, read message instead of comments on leads, and expect appointments / test_drives on the root object when present. v3 also includes provider on each nested lead (id / name may be null when unset).

Authorization: Token is OPTIONAL and can be discarded in the request if the Webhook Url doesn’t require authorization

POST webhook_api_url

The webhook_api_url parameter indicates the target system’s URL for lead export. The webhook_api_token is transmitted as a Bearer token in the authorization header.

Headers

Header Name	Value / Format	Notes
`Content-Type`	`application/json`	Payload is sent as JSON.
`Accept`	`application/json`	Response expected in JSON format.
`Authorization (OPTIONAL)`	Authorization / X-Authorization	Supported Methods: API KEY: Header `X-Authorization: <token>` Bearer Token: Header `Authorization: Bearer <token>`
`X-Signature (OPTIONAL)`	Base64 HMAC-SHA256	Present only when a signing secret is configured. See Payload signature.

Payload signature (optional)

If you need to verify that a delivery genuinely came from Dealer Studio, we can configure a shared signing secret for your webhook. Email support@dealerstudio.com.au to have one set up. Store your copy somewhere safe when we share it: the secret cannot be read back out of Dealer Studio afterwards, so a lost secret has to be replaced with a new one.

When a secret is configured, every POST carries one extra header:

Header	Value
`X-Signature`	Base64-encoded HMAC-SHA256 of the raw request body, keyed with your shared secret

When no secret is configured the header is absent and delivery is unchanged, so this is safe to adopt at any point without a coordinated cutover.

Verifying the signature

Compute the HMAC over the raw request body exactly as received, before any JSON parsing. Parsing and re-serialising the JSON can reorder keys or change whitespace, which produces a different signature. Compare the result in constant time rather than with plain string equality.

const crypto = require('crypto')

function signatureValid(rawBody, secret, headerValue) {
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('base64')
  const a = Buffer.from(expected)
  const b = Buffer.from(headerValue || '')
  return a.length === b.length && crypto.timingSafeEqual(a, b)
}

Most web frameworks buffer and discard the raw body once they have parsed JSON, so you may need to opt in to keeping it. In Express, capture it with the verify option on express.json(). In Rails, read request.raw_post. In Django, read request.body before touching the parsed payload.

What the signature does and does not prove

A valid signature proves the payload was produced by someone holding the shared secret and that it has not been altered in transit.

It does not include a timestamp or nonce, so on its own it does not tell you whether a request is a replay of an earlier captured delivery. If replay protection matters to you, reject deliveries carrying a lead or cluster ID and payload you have already processed.

The signature is independent of the Bearer token described above. You can use either, both, or neither.

Response

Field	Value Required?	Description
Id	Yes	ID of Lead Cluster in Dealer Studio
dealership_id	Yes	ID of Dealer associated with Lead Cluster in Dealer Studio
provider	Yes	provider. default as Dealer Studio
status	Yes	Status of Lead Cluster (from Status Options shown below)
contact	Yes	Contact Details of Lead Cluster as shown below
approver	Yes	approve details of lead cluster as below. this is the person who approved the status changes of lead Cluster
assigned_salesperson	Yes	assigned sales person details of lead cluster as below
created	Yes	Created_at timestamp of Lead Cluster
modified	Yes	updated_at timestamp of Lead Cluster
first_lead_created_at	Yes	Created time of the first lead of Lead Cluster
last_lead_created_at	Yes	created time of the last lead of Lead Cluster
vehicles_of_interest	Yes	Vehicles of interest on the lead cluster (see below)
leads	Yes	Array of leads associated with lead Cluster in Dealer Studio
lead_events	Yes	Lead events associated to the lead Cluster recorded in DS
sold_vehicle	No	Sold vehicle details when status type is converted, delivered, or sold (see below)

Vehicles of interest

Each entry in vehicles_of_interest represents a vehicle the customer is interested in (CarLeadCluster on the lead cluster).

Field	Value Required?	Description
id	Yes	Car lead cluster ID in Dealer Studio
primary	Yes	Whether this is the primary vehicle of interest
intent_to_purchase	Yes	Whether the customer intends to purchase this vehicle
make	No	Manufacturer name (from stock car or catalogue)
model	No	Model name (from stock car or catalogue)
badge	No	Variant / badge
year	No	Model year
colour	No	Exterior colour
interior_colour	No	Interior colour
stock_number	No	Dealer stock number when a VIN is allocated
vin	No	VIN when a stock car is linked
status	No	Stock car status when allocated
car_type	No	`new`, `used`, or `demo` when allocated
price	No	Stock car price when allocated
rego	No	Registration plate when allocated
url	No	Vehicle listing URL when allocated

Sold vehicle

When the lead cluster status type is converted, delivered, or sold, the payload includes sold_vehicle with the same fields as a lead Item (see Item table below), resolved from the latest active sales contract’s allocated car, or the cluster’s primary car when no contract car is available.

Contact

Field	Value Required?	Description
business_name	No	Lead’ Cluster’s customer business name /title
first_name	Yes	Lead Cluster customer first name
last_name	Yes	Lead Cluster customer last name
email	Yes	Lead Cluster customer email
postcode	No	Lead Cluster customer postcode field
mobile_phone	Yes	Lead Cluster customer Phone
dob	No	Lead Cluster customer Date of Birth if provided else returned nil

Approver

Field	Value Required?	Description
id	Yes	Approver Id of Lead Cluster in DS
name	Yes	name of approver approved lead Cluster status change in DS

Assigned SalesPerson

Field	Value Required?	Description
id	Yes	Assigned User Id of Lead Cluster in DS
name	Yes	name of Assigned User of lead Cluster in DS

Lead Attributes

Field	Value Required?	Description
id	Yes	Lead ID in Dealer Studio
website_url	No	Lead’s website url
source	Yes	Source from the list below
category	Yes	Category from the list below
location	Yes	Location details from where the Lead submitted – Mostly within the dealer’s location that exist in DS. object details explained below
prospect	Yes	Lead Customer details as object from below Prospect fields
subscription	Yes	Lead’s subscription object fields below
comments	No	Lead’s message
created	Yes	Lead created_at
modified	Yes	Lead updated_at
booking_date	No	Appointment date set for Test Drive Bookings or Service Bookings with date as string. For other enquiries it will not be part of payload.
booking_time	No	Appointment time set for Test Drive Bookings or Service Bookings with time as string. For other enquiries it will not be part of payload.
item	Yes	Lead vehicle details as object with below Item fields
additional_details	No	This holds any fields that are not mapped to any existing key in the payload get mapped here
trade_in_data	No	This includes lead’s field values when Enquiry Type is Trade-In Enquiry or Sell My Car Enquiry. For other enquiries this field is not mapped.
offer_data	No	This includes lead’s field values when Enquiry Type is Special Offer Enquiry. For other enquiries this field is not mapped.
budget	No	Lead’s vehicle budget if Category is Finance Enquiry
purchase_price	No	Lead’s Purchase Price budget if Category is Finance Enquiry

Location

Field	Value Required?	Description
street	Yes	Street from Location details of Lead (one of the Dealership Locations)
suburb	No	Suburb of the Location details. It is OPTIONAL
city	Yes	City from Location details of Lead (one of the Dealership Locations)
state	Yes	State from Location details of Lead (one of the Dealership Locations)
postcode	Yes	Postcode from Location details of Lead (one of the Dealership Locations)

Prospect

Field	Value Required?	Description
name	Yes	Lead’s first name
last_name	Yes	Lead’s last name
email	Yes	Lead’s customer email
postcode	No	Lead postcode field
home_phone	No	Lead’s Phone
mobile_phone	Yes	Lead’s Mobile Phone
address	No	Address details of Lead (if provided on lead creation). it is returned nil if no address mapped for Lead
licence_type	No	Lead’s licence_type if Category is Finance Enquiry, else returned nil
driver_licence_number	No	Lead’s driver licence if Category is Finance Enquiry else returned nil
employment_type	No	Lead’s Employment Type if Category is Finance Enquiry else returned nil
dob	No	Lead’s Date of Birth if provided else returned nil
residency_status	Yes	Lead’s residency status if provided else returned nil

Address

Field	Value Required?	Description
street	Yes	Street from Location details of Lead (one of the Dealership Locations)
city	Yes	City from Location details of Lead (one of the Dealership Locations)
state	Yes	State from Location details of Lead (one of the Dealership Locations)
postcode	Yes	Postcode from Location details of Lead (one of the Dealership Locations)

Subscription

Field	Value Required?	Description
newsletter	Yes	Lead’s opt_in Default: true

Item

Field	Value Required?	Description
type	Yes	‘Car’
car_type	Yes	Car’s car type from below list
id	No	Lead’s car Id
vin	No	Car’s Vin of Lead
status	No	Status of Vehicle attached to Lead. It will be any of these values: In Stock, Sold, Coming soon. null if no vehicle attached
colour	No	Car’s colour
body_type	No	Car’s Body Type
redbook_code	No	Car’s redbook code
build_date	No	Car’s build date
transmission	No	Car’s transmission either Automatic or Manual
interior_colour	No	Car’s interior colour
stock_number	No	Lead’s car stock_num
deposit	No	Lead’s Deposit amount if Category is Finance Enquiry
make	No	Car make (manufacturer name) value of the lead
model	No	Car model of the lead
badge	No	Car badge of the lead
year	No	Car year value of lead
price	No	Car price
rego	No	Car rego
engine_size	No	Engine Size of Car
km	No	Car kms
comments	No	Dealer comments of Car
series	No	Series of Car
url	No	Car’s url or Lead url
spin_code	No	Spin code of car
third_party_integrations	No	Car’s third party integrations existed on DS

Trade-In Data

Field	Value Required?	Description
rego	Yes	rego of the detail submitted through form on website
kms	Yes	Kms on Lead Fields
state	Yes	State selected on Trade-In form
title	Yes	Combination of Year, make, model, badge, series
year	Yes	Year of Car from Lead Fields
make	Yes	Make of Car from Lead Fields
model	Yes	Model of Car from Lead Fields
badge	Yes	Badge of Car from Lead Fields
series	Yes	Series of Car from Lead Fields
retail_price	Yes	Retail price after valuation of the car
trade_price	Yes	Trading price of the car after valuation
price_adjustment	Yes	Price adjustment made after valuation
offer_price	Yes	Offered price for Lead Fields car
offer_accepted	Yes	Flag to determine whether the user accepted the offer or not. Values are true or false as boolean

Offer Data

Field	Value Required?	Description
manufacturer	No	Manufacturer of Car
offer_name	No	Offer title

Lead Events Attributes

Field	Value Required?	Description
id	Yes	ID of the lead event in DS
event_type	Yes	Type of the event associated. Any one of these: [‘email’, ‘phone’, ‘sms’, ‘test_drive’, ‘note’]
description	Yes	description of the event
created_at	Yes	CreatedAt timestamp of the event in DS system
updated_at	Yes	UpdatedAt timestamp of the event in DS system
external_service	No	Service from which the lead event is created.
deleted_at	No	deleted_at if in case the lead event is deleted at DS
followup_reason	No	reason for follow up of the lead event with lead
followup_datetime	No	Time of the followup of the event
followup_status	Yes	Status of the lead event. It will be any one of the below: [‘pending’, ‘completed’]
followup_completed_at	No	Follow up Completedat timestamp of the event
user_name	No	User created the Lead event

Example Payload

{
  "id": 112233,
  "dealership_id": 121,
  "provider": "Dealer Studio",
  "status": "New",
  "contact": {
    "business_name": null,
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@hotmail.com",
    "dob": null,
    "postcode": 4567,
    "mobile_phone": "+61411111111"
  },
  "approver": {
    "id": 12,
    "name": "Approver"
  },
  "assigned_salesperson": {
    "id": 112,
    "name": "Salesperson"
  },
  "created": "2025-03-13T12:08:32.458Z",
  "modified": "2025-03-13T12:22:11.904Z",
  "pipeline": {
    "id": 123,
    "name": "Sales"
  },
  "first_lead_created_at": "2025-03-13T12:21:08.000Z",
  "last_lead_created_at": "2025-03-13T12:21:08.000Z",
  "vehicles_of_interest": [
    {
      "id": 501,
      "primary": true,
      "intent_to_purchase": true,
      "make": "Haval",
      "model": "jolion",
      "badge": "gasda",
      "year": 2011,
      "colour": "white",
      "stock_number": "aqlrny",
      "vin": "ASHJNBV436",
      "status": "In stock",
      "car_type": "new",
      "price": 81475.0,
      "url": "https://www.tinthouse.com.au/cars/demo-2011-haval-jolion-aqlrny"
    }
  ],
  "sold_vehicle": {
    "type": "Car",
    "car_type": "new",
    "id": 103108,
    "vin": "ASHJNBV436",
    "status": "Sold",
    "colour": "white",
    "stock_number": "aqlrny",
    "make": "Haval",
    "model": "jolion",
    "badge": "gasda",
    "year": 2011,
    "price": 81475.0,
    "url": "https://www.tinthouse.com.au/cars/demo-2011-haval-jolion-aqlrny"
  },
  "leads": [
    {
      "id": 1041902,
      "website_url": null,
      "source": "Carsales",
      "category": "Used Vehicle Enquiry",
      "location": {
        "street": "116 Eagle St",
        "city": "Eagle Farm",
        "state": "QLD",
        "postcode": 4009
      },
      "prospect": {
        "title": "Mr",
        "name": "SMS",
        "last_name": "Connect Prospect",
        "middle_name": null,
        "email": null,
        "postcode": 4009,
        "home_phone": null,
        "mobile_phone": "+61414632323",
        "address": null,
        "dob": null,
        "licence_type": "Full",
        "driver_licence_number": "123456789",
        "employment_type": "Full Time",
        "living_situation": "Owning",
        "residency_status": "Citizen"
      },
      "subscription": {
        "newsletter": false
      },
      "comments": "Thank you \nMy partner is looking for a new car , are you open over the weekend ?",
      "budget": "$60,000",
      "purchase_price": 60000.0,
      "created": "2025-03-13T12:22:11.235Z",
      "modified": "2025-03-13T12:22:11.235Z",
      "item": {
        "type": "Car",
        "car_type": "new",
        "id": 103108,
        "vin": "ASHJNBV436",
        "status": "In stock",
        "colour": "white",
        "body_type": "Ute",
        "stock_number": "aqlrny",
        "redbook_code": "REDH21321",
        "build_date": "2022-02-25",
        "transmission": "Automatic",
        "interior_color": "Red",
        "deposit": 2000.55,
        "make": "Haval",
        "model": "jolion",
        "badge": "gasda",
        "year": 2011,
        "rego": "123VEV",
        "price": 81475.0,
        "engine_size": "2.0L",
        "km": 17368.0,
        "series": "Cannon",
        "comments": "Great Car!!",
        "url": "https://www.tinthouse.com.au/cars/demo-2011-haval-jolion-aqlrny",
        "spin_code": "1725593452345_dsfd34faq324fer4r5r34dfst4gfvdrsger",
        "third_party_integrations": [
          {
            "service": "Autograb",
            "external_id": "abc123"
          }
        ]
      },
      "additional_details": {
        "more_details": "details"
      },
      "booking_date": "2025-03-13",
      "booking_time": "12:00PM",
      "trade_in_data": {
        "rego": "151VEV",
        "kms": 350000,
        "state": "QLD",
        "title": "2014 Mazda CX-5 Maxx KE Series Manual MY14",
        "year": 2014,
        "make": "Mazda",
        "model": "CX-5",
        "badge": "Maxx",
        "series": "KE Series",
        "retail_price": 8506,
        "trade_price": 5529,
        "price_adjustment": 0,
        "offer_price": 5529,
        "offer_accepted": true
      },
      "offer_data": {
        "manufacturer": "Manufacturer ABC",
        "offer_name": "Offer 1234"
      }
    }
  ],
  "lead_events": [
    {
      "id": 6,
      "event_type": "sms",
      "description": "Tried calling, but didnt answer!",
      "created_at": "2024-06-04T01:06:20.343Z",
      "updated_at": "2024-06-04T01:06:20.343Z",
      "external_service": "Impel",
      "deleted_at": null,
      "followup_reason": null,
      "followup_datetime": null,
      "followup_status": "completed",
      "followup_completed_at": "2024-06-04T03:06:20.343Z",
      "user_name": "John Don"
    }
  ]
}

Category Options

Category is required, and must be one of the following:

New Vehicle Enquiry
Used Vehicle Enquiry
Special Offer Enquiry
Test Drive Booking
Trade-in Enquiry
Sell My Car Enquiry
Fleet Enquiry
Service Booking
Service Enquiry
Parts Enquiry
General Enquiry
Finance Enquiry
Insurance Enquiry
Competition Enquiry
Survey
Subscription Enquiry
Team Member Enquiry

Source Options

Source is required and must be one of the following:

Website
Facebook
Facebook Marketplace
Chatbot
Chatbot – External
QR Code
Carsales
Autotrader
Walk In
Phone call

Status Options

Status is required and must be one of the following:

New
Contacted
Lost
Converted

There can be other status options set by dealer in Dealer Studio.

Item Type Options

Item Type is required and must be one of the following:

Car
Motorcycle
Boat
Caravan
Truck
Trailer
Bus
Machinery
Other