Webhooks 101: zo laat de LotShow API je weten dat een foto klaar is

Een studiofoto heeft even tijd nodig. Je systeem kan LotShow om de paar seconden vragen of hij al klaar is, of LotShow kan je systeem laten weten zodra het zover is. Die tweede manier is een webhook, en zo levert de LotShow API resultaten af.

Pollen of webhooks

Pollen betekent dat je code op een timer GET /v1/jobs/{id} aanroept tot de status verandert. Dat werkt, maar de meeste van die calls leveren niets nieuws op, en hoe meer auto's je verwerkt, hoe meer calls je doet.

Een webhook draait dat om. Als je een job aanmaakt, geef je LotShow een URL. Is de job klaar, dan stuurt LotShow een HTTPS POST met het resultaat naar die URL. Je systeem doet niets tot er iets te doen is.

De events

• job.completed: een studiofoto staat klaar, met de URL van het afgewerkte beeld.
• job.failed: een foto kon niet worden afgewerkt en de credit is terugbetaald.
• credits.low: je gedeelde saldo is onder de 20 credits gezakt.

Je kiest per endpoint welke events het ontvangt, zodat een voorraadsysteem kan luisteren naar afgewerkte foto's terwijl een facturatietool alleen hoort over een laag saldo.

Hoe een aflevering eruitziet

Een afgewerkte job komt binnen als een kleine 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
}

De id is het job-id dat je terugkreeg toen je de job aanmaakte. Daarom loont het om het job-id naast het voorraadnummer op te slaan in je eigen systeem: de webhook vertelt je welke job klaar is, en je eigen administratie vertelt je bij welke auto hij hoort.

Een goed endpoint bouwen

1. Antwoord snel. Reageer met een 2xx-status zodra het event binnen is, en doe het echte werk, zoals het beeld downloaden, op de achtergrond.
2. Reken op herhalingen. Een aflevering kan vaker dan één keer binnenkomen, bijvoorbeeld na een time-out, omdat LotShow het opnieuw probeert tot je endpoint antwoordt. Controleer of je een event al hebt verwerkt voordat je er opnieuw iets mee doet.
3. Ga niet uit van een volgorde. Twee jobs die een seconde na elkaar zijn verstuurd, kunnen in willekeurige volgorde klaar zijn. Koppel resultaten op job-id, niet op het moment van binnenkomst.
4. Controleer de handtekening. Elke aflevering is ondertekend met het ondertekeningsgeheim van je account, uit Instellingen, in de headers webhook-id, webhook-timestamp en webhook-signature (het schema van Standard Webhooks). Weiger alles wat de controle niet doorstaat.
5. Log alles. Bewaar de ruwe body en het tijdstip van elke aflevering. Ziet iets er verkeerd uit, dan is de log de eerste plek waar je kijkt.

Testen voordat je live gaat

Elk endpoint in Instellingen heeft een knop Test sturen, en de API heeft POST /v1/webhooks/{id}/test. Beide sturen een voorbeeldevent naar je endpoint, zodat je je handler kunt testen zonder credits uit te geven. Een request-inspector of een lokale tunnel is een prima manier om precies te zien wat je endpoint ontvangt.

Klaar om te bouwen? API-sleutels horen bij Pro en Elite: maak er een aan in Instellingen, onder API-sleutels.