Webhook'lara giriş: LotShow API bir fotoğrafın hazır olduğunu size nasıl bildirir?

Bir stüdyo fotoğrafının bitmesi biraz zaman alır. Sisteminiz birkaç saniyede bir LotShow'a işin bitip bitmediğini sorabilir ya da LotShow, bittiği anda sisteminize haber verebilir. İkinci yolun adı webhook'tur ve LotShow API sonuçları bu yolla iletir.

Yoklama mı, webhook mu?

Yoklama, kodunuzun durum değişene kadar bir zamanlayıcıyla GET /v1/jobs/{id} çağırması demektir. İşe yarar, ama bu çağrıların çoğu yeni bir şey getirmez ve ne kadar çok araç işlerseniz o kadar çok çağrı yaparsınız.

Webhook bunu tersine çevirir. Bir iş oluştururken LotShow'a bir URL verirsiniz. İş bittiğinde LotShow sonucu o URL'ye bir HTTPS POST ile gönderir. Yapılacak bir şey olana kadar sisteminiz hiçbir şey yapmaz.

Olaylar

• job.completed: bir stüdyo fotoğrafı hazır; bitmiş görselin URL'siyle birlikte.
• job.failed: bir fotoğraf tamamlanamadı ve kredisi iade edildi.
• credits.low: ortak bakiyeniz 20 kredinin altına düştü.

Her uç noktanın hangi olayları alacağını siz seçersiniz; böylece bir stok sistemi bitmiş fotoğrafları dinlerken bir faturalama aracı yalnızca düşük bakiyelerden haberdar olur.

Bir teslimat nasıl görünür?

Bitmiş bir iş, küçük bir JSON gövdesi olarak gelir:

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

id, işi oluşturduğunuzda geri aldığınız iş kimliğidir. Bu yüzden iş kimliğini kendi sisteminizde stok numarasının yanında saklamak işe yarar: webhook hangi işin bittiğini, kayıtlarınız da onun hangi araca ait olduğunu söyler.

İyi bir uç nokta kurmak

1. Hızlı yanıt verin. Olay gelir gelmez 2xx durumuyla yanıt verin, ardından görseli indirmek gibi asıl işi arka planda yapın.
2. Tekrarları bekleyin. Bir teslimat, örneğin bir zaman aşımından sonra, birden fazla kez gelebilir; çünkü LotShow uç noktanız yanıt verene kadar yeniden dener. Bir olaya yeniden işlem yapmadan önce onu daha önce işleyip işlemediğinizi kontrol edin.
3. Sıra varsaymayın. Bir saniye arayla gönderilen iki iş herhangi bir sırayla bitebilir. Sonuçları geliş zamanına göre değil, iş kimliğine göre eşleştirin.
4. İmzayı doğrulayın. Her teslimat, hesabınızın Ayarlar'da bulunan imza sırrıyla webhook-id, webhook-timestamp ve webhook-signature başlıklarında imzalanır (Standard Webhooks şeması). Doğrulanamayan her şeyi reddedin.
5. Her şeyi kaydedin. Her teslimatın ham gövdesini ve zamanını saklayın. Bir şey ters gittiğinde ilk bakacağınız yer kayıtlar olacak.

Yayına almadan önce test

Ayarlar'daki her uç noktanın bir Test gönder düğmesi vardır, API'de ise POST /v1/webhooks/{id}/test bulunur. İkisi de uç noktanıza örnek bir olay gönderir; böylece kredi harcamadan işleyicinizi kontrol edebilirsiniz. Bir istek inceleyici ya da yerel bir tünel, uç noktanıza tam olarak ne geldiğini görmenin iyi bir yoludur.

Geliştirmeye hazır mısınız? API anahtarları Pro ve Elit ile gelir: Ayarlar'da, API anahtarları bölümünden bir tane oluşturun.