Webhooks

Bir API görevi ilerleme kaydettiğinde veya tamamlandığında Meshy'nin sunucunuza bir POST isteği göndermesini sağlayın; böylece sorgulama yapmanıza gerek kalmaz.

Webhooks neden kullanılır

Webhooks, her görevin durumunu API'den sorgulamaya göre daha az iş gerektirir ve daha düşük maliyetlidir. Meshy her güncellemeyi gerçekleştiği anda gönderir, böylece bunu daha erken alırsınız ve webhooks sorgulamaya göre daha iyi ölçeklenir. Ayrıca daha az istek gönderirsiniz, bu da sizi rate limits değerlerinizden daha uzak tutar.

Webhook kurulumu

Bir webhook eklemek için şu adımları izleyin:

Geliştirici Platformu içindeki Webhooks sayfasını açın ve Create Webhook'a tıklayın.
Payload URL alanına, teslimatları alacak URL'yi girin. Meshy yalnızca https:// üzerinden teslimat yapar.
İletişim kutusunun doldurduğu Webhook Secret değerinin bir kopyasını saklayın. Her teslimat bunu taşır, böylece sunucunuz isteğin Meshy'den geldiğini doğrulayabilir. Zaten sahip olduğunuz bir webhook için, Secret sütunundaki göz simgesine tıklayarak bunu görebilirsiniz.
Active'i seçin ve Confirm'e tıklayın.

Her hesap en fazla 5 aktif webhook'a ve toplamda 10 webhook'a sahip olabilir. Her aktif webhook, tüm API görevlerinizin durum güncellemelerini alır.

Bir webhook'u bilgisayarınızdaki bir sunucuyla test etmek için Bilgisayarınızda test edin bölümüne bakın.

Teslimatı işleme

Bir teslimatı kabul etmek için 400'ün altında bir durum koduyla yanıt verin, örneğin 200 veya 202. Meshy yanıt için yaklaşık 25 saniye bekler, bu yüzden teslimatı önce saklayıp yanıt verin. Model indirme gibi yavaş işleri bundan sonra yapın.

400 veya üzeri bir durum kodu ya da yanıt alınamaması, başarısız bir teslimat sayılır. Meshy bunu, denemeler arasında giderek uzayan beklemelerle yeniden dener; bir IN_PROGRESS güncellemesi için en fazla 4 kez, nihai bir durum için en fazla 9 kez. Art arda 20 güncelleme her denemede başarısız olursa, Meshy webhook'u devre dışı bırakabilir. Onu tekrar açmak için, Webhooks sayfasında düzenleyin ve Active'i seçin.

Kodunuzu şu durumlar için yazın:

Teslimatlar sırasız gelebilir. Bir IN_PROGRESS teslimatı, nihai teslimattan sonra gelebilir, bu yüzden bunun nihai bir durumun yerini almasına izin vermeyin.
Aynı güncelleme birden fazla kez gelebilir. Her id ve status çiftini yalnızca bir kez işleyin.
URL'nizi bilen herkes ona bir istek gönderebilir. X-MESHY-API-WEBHOOK-SECRET-KEY değerini gizli anahtarınızın kopyasıyla karşılaştırın ve eşleşmeyen bir isteği reddedin.

Bir görevin nihai teslimatı, o görevin tipik süresinin yaklaşık iki katından sonra hâlâ gelmemişse, görevi GET uç noktasından alın. Tipik süreler ve ne kadar beklenmesi gerektiği hakkında bilgi için bkz. Görev yaşam döngüsü.

Bilgisayarınızda test edin

Meshy yalnızca genel (public) bir https:// URL'sine teslimat yapar, bu yüzden bilgisayarınızdaki bir sunucuya doğrudan ulaşamaz. Bilgisayarınızdaki kodu test etmek için, bir webhook proxy ile genel bir URL'yi ona yönlendirin. Bu adımlar smee.io kullanır; herhangi bir webhook proxy hizmeti aynı şekilde çalışır.

smee.io adresini açın ve Start a new channel'a tıklayın. Webhook Proxy URL altındaki URL'yi kopyalayın.
Henüz smee istemciniz yoksa, kurun:
```
npm install --global smee-client
```
Kanalı sunucunuza yönlendirin. WEBHOOK_PROXY_URL yerine kendi webhook proxy URL'nizi yazın:
```
smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000
```
Çıktı şöyle görünür; burada WEBHOOK_PROXY_URL sizin webhook proxy URL'nizdir:
```
Forwarding WEBHOOK_PROXY_URL to http://127.0.0.1:3000/webhook
Connected WEBHOOK_PROXY_URL
```
Test ederken bunu çalışır durumda tutun. Yönlendirmeyi durdurmak için Ctrl+C tuşlarına basın. Sunucunuz teslimatları 3000 portundaki /webhook yolunda alır, bu yüzden kodunuzu orayı dinleyecek şekilde ayarlayın.
Webhooks sayfasında, Payload URL olarak webhook proxy URL'si ile bir webhook oluşturun.

Teslimat yükü

Meshy, bir görev IN_PROGRESS durumundayken bir teslimat gönderir ve görev nihai bir duruma ulaştığında bir tane daha gönderir. Bir görev, bir IN_PROGRESS teslimatı olmadan da nihai durumuna ulaşabilir.

Her teslimat, Payload URL'nize şu başlıklarla yapılan bir POST isteğidir:

Başlık	Değer
`X-MESHY-API-WEBHOOK-SECRET-KEY`	Webhook'un gizli anahtarı
`X-MESHY-API-WEBHOOK-USER-ID`	Webhook'a sahip olan Meshy kullanıcısının kimliği
`Meshy-Webhook-Version`	`v1`, gövdenin biçimi
`Content-Type`	`application/json`
`User-Agent`	`MeshyAPIWebhook/1.0.0`

JSON gövdesi görev nesnesidir. Bu, görevin GET uç noktasının döndürdüğü nesneyle aynıdır, yalnızca progress hariç. Bir teslimat, progress değerini şu değerlerden biri olarak gönderir:

Görev IN_PROGRESS durumundayken 50
Görev başarılı olduğunda 100
Görev başarısız olduğunda veya iptal edildiğinde 0

Her görev nesnesinin alanları ve bir örnek için aşağıdaki bölümlere bakın: