Dealer API and lead webhook

Keys

A manager or the owner makes a key under API keys in the dealer console. The key starts with bd_live_ and is shown once: we keep only a fingerprint of it. Send it on every request as Authorization: Bearer followed by the key. A key may do one or both of:

• listings:write: list, add, change and withdraw your ads, send their photos, and read the result of each change;
• leads:read: read your leads and their messages.

Each key may make 600 requests an hour; past that the answer is 429 with a Retry-After header. Every call is logged against the key. Revoke a key from the console and it stops at once. Keys stop working while the dealership has no Pro or Group plan, and start again when it does.

Endpoints

All answers are JSON. Times are ISO 8601.

Adding or changing an ad

PUT /api/v1/listings/A1234
Authorization: Bearer bd_live_...
Content-Type: application/json

{
  "make": "Jayco",
  "model": "Journey",
  "year": 2021,
  "price": 58990,
  "condition": "used",
  "category": "caravans",
  "atm_kg": 2900,
  "tare_kg": 2400,
  "length": "19'6"",
  "axle_config": "tandem",
  "berths": 4,
  "ensuite": true,
  "water_l": 190,
  "colour": "White",
  "rego_status": "registered",
  "rego_no": "ABC123",
  "description": "One owner, serviced by us, new tyres. Comes with the spare key and books.",
  "photo": ["https://images.dealer.example/a1234-1.jpg", "https://images.dealer.example/a1234-2.jpg"]
}

201 {"status": "created", "listing_id": 100512, "run_id": 88, "warnings": []}
202 {"status": "invalid", "run_id": 89, "errors": [{"field": "year", "code": "year_out_of_range", "message": "..."}], "warnings": []}

An ad that fails the checks is answered 202 with an errors list, one entry per field, and nothing is saved. The VIN, chassis number and engine number are stored encrypted and never returned by the API. Only a dealer's ad shows one, and only where the dealer's state requires it.

Fields

Answers you may get

• 400 a request we cannot read; 401 a missing, unknown or revoked key; 403 a key without the scope, or a dealership that is not verified or has no Pro or Group plan; 404 not one of your ads or runs; 409 an ad in a state that does not allow it; 413 a body over 64 KB; 429 too many requests; 503 Caravan Domain is read-only for a moment (try again later).

Lead webhook

On the Pro and Group plans you can give us an https address under your dealership profile. We post each new lead there as JSON. If your address does not answer with a 2xx status we try again three times, after 1, 5 and 25 minutes. We never follow a redirect, and addresses on private or internal networks are refused.

POST (your address)
Content-Type: application/json
X-CaravanDomain-Event: lead.created
X-CaravanDomain-Delivery: 5521
X-CaravanDomain-Signature: t=1790000000,v1=5f0c...

{
  "event": "lead.created",
  "id": "8d5e...",
  "created_at": "2026-10-01T09:30:00.000Z",
  "listing": {"id": 100512, "stock_no": "A1234", "title": "2021 Jayco Journey", "year": 2021,
              "make": "Jayco", "model": "Journey", "price_cents": 5899000, "url": "https://caravandomain.com.au/caravan/..."},
  "customer": {"name": "Sam", "phone": "+61400000000"},
  "message": "Hi, is this van still available?"
}

Each post is signed with your webhook secret (shown once when you set the address; make a new one from your profile at any time). Check the X-CaravanDomain-Signature header before you trust the body, and refuse one older than five minutes:

import { createHmac, timingSafeEqual } from 'node:crypto';

// header: the X-CaravanDomain-Signature value, body: the raw request body as received
export function verify(secret, body, header, nowSeconds) {
  const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header);
  if (!m || Math.abs(nowSeconds - Number(m[1])) > 300) return false;
  const want = createHmac('sha256', secret).update(m[1] + '.' + body).digest();
  const got = Buffer.from(m[2], 'hex');
  return got.length === want.length && timingSafeEqual(got, want);
}

ADF lead emails

Any dealer can also have each new lead emailed to their dealer system in the ADF 1.0 format, one lead per email. Set the address under your dealership profile and send a test lead from there. The buyer's email address is in it only when they agreed to share it.