Webhooks 101: How the LotShow API Tells You a Photo Is Ready

A studio photo takes a little while to finish. Your system could ask LotShow every few seconds whether it's done yet, or LotShow can tell your system the moment it is. That second way is a webhook, and it's how the LotShow API delivers results.

Polling or Webhooks

Polling means your code calls GET /v1/jobs/{id} on a timer until the status changes. It works, but most of those calls come back with nothing new, and the more cars you process, the more of them you make.

A webhook turns that around. When you create a job, you give LotShow a URL. When the job finishes, LotShow sends an HTTPS POST to that URL with the result. Your system does nothing until there's something to do.

The Events

• job.completed: a studio photo is ready, with the URL of the finished image.
• job.failed: a photo couldn't be finished, and its credit has been refunded.
• credits.low: your shared balance dropped below 20 credits.

You choose which events each endpoint receives, so a stock system can listen for finished photos while a billing tool only hears about low balances.

What a Delivery Looks Like

A finished job arrives as a small JSON body:

{
  "event": "job.completed",
  "created_at": "2026-10-14T09:41:40.000Z",
  "id": "Hn4kR2pXq8VbT1sLw0Za",
  "backdrop": "white-hall",
  "vehicle_id": "pQ7mT2vK9cLx4RbN1sHd",
  "name": "stock-4471",
  "output_url": "https://firebasestorage.googleapis.com/v0/b/…/default.jpg?alt=media&token=…",
  "seconds": 62,
  "credits_left": 319
}

The id is the job id you got back when you created the job. That's why it pays to store the job id next to the stock number in your own system: the webhook tells you which job finished, and your records tell you which car it belongs to.

Building a Good Endpoint

1. Answer fast. Reply with a 2xx status as soon as the event has arrived, then do the real work, like downloading the image, in the background.
2. Expect repeats. A delivery can arrive more than once, for example after a timeout, because LotShow retries until your endpoint answers. Check whether you've already handled an event before acting on it again.
3. Don't assume order. Two jobs sent a second apart can finish in either order. Match results by job id, not by when they arrive.
4. Check the signature. Every delivery is signed with your account's signing secret, from Settings, in the webhook-id, webhook-timestamp and webhook-signature headers (the Standard Webhooks scheme). Reject anything that doesn't verify.
5. Log everything. Keep the raw body and the time of every delivery. When something looks wrong, the log is the first place you'll look.

Testing Before You Go Live

Each endpoint in Settings has a Send test button, and the API has POST /v1/webhooks/{id}/test. Both send a sample event to your endpoint, so you can check your handler without spending credits. A request inspector or a local tunnel is a fine way to see exactly what your endpoint receives.

Ready to build? API keys come with Pro and Elite: make one in Settings, under API keys.