Webhooks 101: Wie dir die LotShow API sagt, dass ein Foto fertig ist

Ein Studiofoto braucht ein wenig Zeit. Dein System könnte LotShow alle paar Sekunden fragen, ob es schon fertig ist, oder LotShow sagt deinem System in dem Moment Bescheid, in dem es so weit ist. Der zweite Weg ist ein Webhook, und so liefert die LotShow API Ergebnisse.

Polling oder Webhooks

Polling heißt, dass dein Code per Timer GET /v1/jobs/{id} aufruft, bis sich der Status ändert. Das funktioniert, aber die meisten dieser Aufrufe bringen nichts Neues, und je mehr Autos du verarbeitest, desto mehr davon machst du.

Ein Webhook dreht das um. Wenn du einen Job anlegst, gibst du LotShow eine URL. Ist der Job fertig, sendet LotShow einen HTTPS-POST mit dem Ergebnis an diese URL. Dein System tut nichts, bis es etwas zu tun gibt.

Die Events

• job.completed: Ein Studiofoto ist fertig, mit der URL des fertigen Bildes.
• job.failed: Ein Foto konnte nicht fertiggestellt werden, und sein Credit wurde erstattet.
• credits.low: Dein gemeinsames Guthaben ist unter 20 Credits gefallen.

Du legst fest, welche Events jeder Endpunkt empfängt. So kann ein Bestandssystem auf fertige Fotos warten, während ein Abrechnungstool nur von niedrigem Guthaben erfährt.

So sieht eine Zustellung aus

Ein fertiger Job kommt als kleiner JSON-Body an:

{
  "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
}

Die id ist die Job-ID, die du beim Anlegen des Jobs zurückbekommen hast. Deshalb lohnt es sich, die Job-ID in deinem eigenen System neben der Bestandsnummer zu speichern: Der Webhook sagt dir, welcher Job fertig ist, und deine Daten sagen dir, zu welchem Auto er gehört.

Einen guten Endpunkt bauen

1. Schnell antworten. Antworte mit einem 2xx-Status, sobald das Event angekommen ist, und erledige die eigentliche Arbeit, etwa das Herunterladen des Bildes, im Hintergrund.
2. Mit Wiederholungen rechnen. Eine Zustellung kann mehr als einmal ankommen, zum Beispiel nach einem Timeout, denn LotShow versucht es so lange erneut, bis dein Endpunkt antwortet. Prüfe, ob du ein Event schon verarbeitet hast, bevor du erneut darauf reagierst.
3. Keine Reihenfolge voraussetzen. Zwei Jobs, die eine Sekunde auseinander gesendet wurden, können in beliebiger Reihenfolge fertig werden. Ordne Ergebnisse über die Job-ID zu, nicht über den Eingangszeitpunkt.
4. Die Signatur prüfen. Jede Zustellung ist mit dem Signatur-Secret deines Kontos aus den Einstellungen signiert, in den Headern webhook-id, webhook-timestamp und webhook-signature (nach dem Schema von Standard Webhooks). Lehne alles ab, was sich nicht verifizieren lässt.
5. Alles protokollieren. Bewahre den Roh-Body und den Zeitpunkt jeder Zustellung auf. Wenn etwas komisch aussieht, schaust du zuerst ins Log.

Testen, bevor es live geht

Jeder Endpunkt in den Einstellungen hat einen Button „Test senden“, und die API hat POST /v1/webhooks/{id}/test. Beide senden ein Beispiel-Event an deinen Endpunkt, sodass du deinen Handler testen kannst, ohne Credits zu verbrauchen. Ein Request-Inspector oder ein lokaler Tunnel zeigt dir genau, was dein Endpunkt empfängt.

Bereit loszulegen? API-Schlüssel gibt es mit Pro und Elite: Erstelle einen in den Einstellungen unter API-Schlüssel.