Web Kancaları

Web kancaları, üretken bir süreç tamamlandığında eşzamansız bildirimler almanızı sağlar. Güncellemeleri kontrol etmek için /api/v1/status/{id} uç noktasını manuel olarak yoklamak yerine, iş biter bitmez sistemimiz nihai yükü doğrudan sunucunuza gönderir.

Web Kancaları Nasıl Kullanılır

API'mızla web kancalarını kullanmak için, /run isteğinize webhook_url parametresini eklemeniz yeterlidir:

Üretken süreç tamamlandığında (başarılı bir şekilde veya bir çalışma zamanı hatasıyla karşılaşırsa), dağıtıcımız belirtilen web kancası URL'nize eksiksiz durum yükünü içeren bir POST isteği gönderecektir.

Örnek: /run Uç Noktası ile Web Kancalarını Kullanma

fetch("https://fititon.app/api/v1/run?webhook_url=https://your-server.com/webhook", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY",
  },
  body: JSON.stringify({
    model_name: "product-to-model",
    inputs: {
      image: "http://example.com/path/to/garment.jpg",
      // ... other inputs
    }
  }),
});

Web Kancası Yükleri

Web kancası URL'nize teslim edilen yük, /v1/status/{id} uç noktasının döndürdüğü yük ile aynıdır. İşin nihai durumunu içerir.

Başarılı Yük

Süreç başarıyla tamamlandığında, web kancası URL'niz status değeri "success" olarak ayarlanmış ve sonuçları output dizisinde içeren bir POST isteği alacaktır:

{
  "id": "123a87r9-4129-4bb3-be18-9c9fb5bd7fc1",
  "status": "success",
  "output": [
    "https://cdn.fititon.app/users/123/results/output_0.png"
  ],
  "error": null,
  "created_at": "2026-07-24T17:30:00.000Z",
  "updated_at": "2026-07-24T17:31:15.000Z"
}

Hata Yükü

Süreç bir çalışma zamanı hatası nedeniyle başarısız olursa (örn. tanınmayan giysi, katı denetim filtreleri), web kancası URL'niz tam hata dizesini alacaktır.

{
  "id": "123a87r9-4129-4bb3-be18-9c9fb5bd7fc1",
  "status": "failed",
  "output": null,
  "error": {
    "name": "InputValidationError",
    "message": "The provided garment image could not be processed due to poor lighting."
  },
  "created_at": "2026-07-24T17:30:00.000Z",
  "updated_at": "2026-07-24T17:30:12.000Z"
}

Web Kancası Güvenliği

Aldığınız web kancalarının gerçekten Fit It On'dan geldiğinden ve kötü niyetli bir üçüncü tarafça sahtecilik yapılmadığından emin olmak için bir doğrulama mekanizması uygulamanız gerekir.

Web kancalarınızı güvence altına almanın en basit yolu, /v1/run isteğinizde sağladığınız webhook_url'ye gizli bir belirteç eklemektir.

Örnek: Gizli Bir Belirteç Kullanma

Üretken bir süreci başlattığınızda, URL sorgu parametrelerinize oldukça rastgele bir dize ekleyin:

// Make sure to URL-encode the webhook URL if it contains query parameters!
const myWebhookUrl = encodeURIComponent("https://your-server.com/webhook?token=a8f9c2d1e5b47...");

fetch(`https://fititon.app/api/v1/run?webhook_url=${myWebhookUrl}`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY",
  },
  // ...
  body: JSON.stringify({
    model_name: "product-to-model",
    inputs: {
      image: "http://example.com/path/to/garment.jpg",
    }
  }),
});

Sunucunuz web kancası POST isteğini aldığında, JSON yükünü işlemeden önce token sorgu parametresinin gizli dizenizle eşleştiğini doğrulamanız yeterlidir.

Garantili Teslimat ve Yeniden Denemeler

Sistemimiz, sunucunuz geçici olarak kapalı olsa bile hiçbir web kancası teslimatını kaçırmamanızı sağlamak için kurumsal düzeyde bir yeniden deneme mekanizması uygular.

• Zaman Aşımı: Dağıtıcımız katı bir 15 saniyelik zaman aşımı uygular. Sunucunuz, web kancasını 15 saniye içinde bir 2xx HTTP durum koduyla onaylamalıdır. Yoğun işlem yapmanız gerekiyorsa (görüntüyü indirmek gibi), önce web kancasına yanıt vermeli ve verileri eşzamansız olarak işlemelisiniz.
• Başarısızlıklar: Sunucunuz 2xx olmayan bir durum kodu (örn. 500 Internal Server Error) döndürürse veya 15 saniye içinde yanıt veremezse, teslimatı başarısız kabul ederiz.
• Üstel Geri Çekilme: Sistem, üstel geri çekilme kullanarak (örn. 5 dakika, 15 dakika, 45 dakika vb. sonra yeniden deneme) en fazla 5 yeniden deneme yapacaktır.

Sunucunuza hangi yeniden deneme girişiminin ulaştığını bilmeniz gerekiyorsa, her web kancası isteğinde bulunan x-fititon-retry-count başlığını inceleyebilirsiniz.

En İyi Uygulamalar

1. Idempotensi Uygulayın: Ağ koşulları ve yeniden deneme mekanizmamız nedeniyle, sunucunuzun aynı web kancasını birden fazla kez alması teknik olarak mümkündür. Olayı zaten işleyip işlemediğinizi kontrol etmek için id alanını kullanmalısınız.
2. Hızlı Yanıt Verin: Görüntüleri indirmeden veya veritabanlarını güncellemeden önce her zaman hemen bir 200 OK durumu döndürün.
3. Web Kancalarını Her Zaman Doğrulayın: Web kancalarının hizmetimizden geldiğinden emin olmak ve kötü niyetli aktörlerin yükleri taklit etmesini önlemek için (yukarıda bahsedilen gizli URL belirteci gibi) bir doğrulama mekanizması uygulamayı düşünün.