Webhooki od podstaw: jak LotShow API daje ci znać, że zdjęcie jest gotowe

Zdjęcie studyjne potrzebuje chwili, żeby powstać. Twój system mógłby co kilka sekund pytać LotShow, czy już gotowe, albo LotShow może powiadomić twój system w chwili, gdy będzie. Ten drugi sposób to webhook i właśnie tak LotShow API dostarcza wyniki.

Odpytywanie czy webhooki

Odpytywanie oznacza, że twój kod co jakiś czas wywołuje GET /v1/jobs/{id}, aż status się zmieni. To działa, ale większość tych wywołań nie przynosi niczego nowego, a im więcej aut przetwarzasz, tym więcej ich wykonujesz.

Webhook odwraca ten układ. Tworząc zadanie, podajesz LotShow adres URL. Gdy zadanie się zakończy, LotShow wysyła na ten adres żądanie HTTPS POST z wynikiem. Twój system nic nie robi, dopóki nie ma nic do zrobienia.

Zdarzenia

• job.completed: zdjęcie studyjne jest gotowe, z adresem URL gotowego pliku.
• job.failed: nie udało się ukończyć zdjęcia, a jego kredyt został zwrócony.
• credits.low: twoja wspólna pula spadła poniżej 20 kredytów.

Dla każdego endpointu wybierasz, jakie zdarzenia ma otrzymywać, więc system magazynowy może nasłuchiwać gotowych zdjęć, a narzędzie do rozliczeń dostawać tylko informacje o niskim saldzie.

Jak wygląda dostarczenie

Zakończone zadanie przychodzi jako niewielki JSON:

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

Pole id to identyfikator zadania, który wrócił w odpowiedzi przy jego tworzeniu. Dlatego warto zapisywać identyfikator zadania obok numeru magazynowego we własnym systemie: webhook mówi ci, które zadanie się zakończyło, a twoje dane, do którego auta ono należy.

Jak zbudować dobry endpoint

1. Odpowiadaj szybko. Zwróć status 2xx, gdy tylko zdarzenie dotrze, a właściwą pracę, np. pobranie zdjęcia, wykonaj w tle.
2. Spodziewaj się powtórek. To samo dostarczenie może przyjść więcej niż raz, na przykład po przekroczeniu limitu czasu, bo LotShow ponawia próby, dopóki twój endpoint nie odpowie. Zanim zareagujesz na zdarzenie, sprawdź, czy nie zostało już obsłużone.
3. Nie zakładaj kolejności. Dwa zadania wysłane w odstępie sekundy mogą zakończyć się w dowolnej kolejności. Dopasowuj wyniki po identyfikatorze zadania, a nie po czasie nadejścia.
4. Sprawdzaj podpis. Każde dostarczenie jest podpisane sekretem podpisu twojego konta, który znajdziesz w Ustawieniach, w nagłówkach webhook-id, webhook-timestamp i webhook-signature (schemat Standard Webhooks). Odrzucaj wszystko, czego nie da się zweryfikować.
5. Loguj wszystko. Zapisuj surową treść i czas każdego dostarczenia. Gdy coś wygląda źle, dziennik to pierwsze miejsce, do którego zajrzysz.

Testy przed startem

Każdy endpoint w Ustawieniach ma przycisk Wyślij test, a API ma POST /v1/webhooks/{id}/test. Oba wysyłają przykładowe zdarzenie na twój endpoint, więc sprawdzisz swój handler bez wydawania kredytów. Inspektor żądań albo lokalny tunel to dobry sposób, żeby zobaczyć, co dokładnie dostaje twój endpoint.

Chcesz zacząć budować? Klucze API są w planach Pro i Elite: utwórz klucz w Ustawieniach, w sekcji Klucze API.